Yönetilen kimlik aracılığıyla Azure Cosmos DB'ye dizin oluşturucu bağlantısı kurma

  • Makale

Bu makalede, bağlantı dizesi kimlik bilgilerini sağlamak yerine yönetilen kimlik kullanarak Azure Cosmos DB veritabanına dizin oluşturucu bağlantısının nasıl ayarlanacağı açıklanmaktadır.'

Sistem tarafından atanan yönetilen kimliği veya kullanıcı tarafından atanan yönetilen kimliği (önizleme) kullanabilirsiniz. Yönetilen kimlikler Microsoft Entra oturum açma bilgileridir ve Azure Cosmos DB'deki verilere erişmek için Azure rol atamaları gerektirir.

Önkoşullar

  • Arama hizmetiniz için yönetilen bir kimlik oluşturun.

  • Cosmos DB Hesap Okuyucusu rolünü arama hizmeti yönetilen kimliğine atayın. Bu rol, Azure Cosmos DB hesap verilerini okuma olanağı sağlar. Cosmos DB'deki rol atamaları hakkında daha fazla bilgi için bkz . Verilere rol tabanlı erişim denetimini yapılandırma.

  • Veri Düzlemi Rolü ataması: Daha fazla bilgi edinmek için Veri düzlemi Rol atamasını izleyin.

  • Salt okunur veri düzlemi rol ataması örneği:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Sistem tarafından atanan kimlik için rol ataması:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

  • NoSQL için Cosmos DB için, Cosmos DB hesabınız için olarak ayarlayarak disableLocalAuthtrue veri bağlantıları için tek kimlik doğrulama yöntemi olarak isteğe bağlı olarak rol tabanlı erişimi zorunlu kılabilirsiniz.

  • Gremlin ve MongoDB Koleksiyonları için: Dizin oluşturucu desteği şu anda önizleme aşamasındadır. Şu anda Azure AI Search'in anahtarları kullanarak bağlanmasını gerektiren bir önizleme sınırlaması vardır. Yönetilen kimlik ve rol ataması ayarlamaya devam edebilirsiniz, ancak Azure AI Search yalnızca bağlantı anahtarlarını almak için rol atamasını kullanır. Bu sınırlama, dizin oluşturucularınız Azure Cosmos DB'ye bağlanmak için yönetilen kimliklerle Arama'yı kullanarak Gremlin veya MongoDB'ye bağlanıyorsa rol tabanlı bir yaklaşım yapılandıramazsınız.

  • Dizin oluşturucu kavramları ve yapılandırması hakkında bilgi sahibi olmanız gerekir.

Veri kaynağı oluşturma

Veri kaynağını oluşturun ve bağlantı dizesi sistem tarafından atanan yönetilen kimlik veya kullanıcı tarafından atanan yönetilen kimlik (önizleme) sağlayın.

Sistem tarafından atanan yönetilen kimlik

REST API, Azure portalı ve .NET SDK'sı sistem tarafından atanan yönetilen kimliğin kullanılmasını destekler.

Sistem tarafından atanan yönetilen kimlikle bağlanırken, veri kaynağı tanımında yapılan tek değişiklik "kimlik bilgileri" özelliğinin biçimidir. Veritabanı adını ve hesap anahtarı veya parolası olmayan bir ResourceId sağlayacaksınız. ResourceId, Azure Cosmos DB abonelik kimliğini, kaynak grubunu ve Azure Cosmos DB hesap adını içermelidir.

  • SQL koleksiyonları için bağlantı dizesi "ApiKind" gerektirmez.
  • SQL koleksiyonları için rol tabanlı erişim tek kimlik doğrulama yöntemi olarak zorlanırsa "IdentityAuthType=AccessToken" ekleyin. MongoDB ve Gremlin koleksiyonları için geçerli değildir.
  • MongoDB koleksiyonları için bağlantı dizesi "ApiKind=MongoDb" ekleyin ve önizleme REST API'sini kullanın.
  • Gremlin grafikleri için bağlantı dizesi "ApiKind=Gremlin" ekleyin ve önizleme REST API'sini kullanın.

Veri Kaynağı Oluşturma REST API'sini ve yönetilen kimlik bağlantı dizesi kullanarak depolama hesabından verileri dizine almak için veri kaynağı oluşturma örneği aşağıda verilmiştir. Yönetilen kimlik bağlantı dizesi biçimi REST API, .NET SDK ve Azure portalı için aynıdır.

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Kullanıcı tarafından atanan yönetilen kimlik (önizleme)

2021-04-30-preview REST API,kullanıcı tarafından atanan yönetilen kimliğe dayalı bağlantıları destekler. Kullanıcı tarafından atanan bir yönetilen kimlikle bağlanırken, veri kaynağı tanımında iki değişiklik vardır:

  • İlk olarak, "credentials" özelliğinin biçimi veritabanı adı ve hesap anahtarı veya parolası olmayan bir ResourceId'dir. ResourceId, Azure Cosmos DB abonelik kimliğini, kaynak grubunu ve Azure Cosmos DB hesap adını içermelidir.

    • SQL koleksiyonları için bağlantı dizesi "ApiKind" gerektirmez.
    • SQL koleksiyonları için rol tabanlı erişim tek kimlik doğrulama yöntemi olarak zorlanırsa "IdentityAuthType=AccessToken" ekleyin. MongoDB ve Gremlin koleksiyonları için geçerli değildir.
    • MongoDB koleksiyonları için bağlantı dizesi "ApiKind=MongoDb" ekleyin
    • Gremlin grafikleri için bağlantı dizesi "ApiKind=Gremlin" ekleyin.

  • İkincisi, kullanıcı tarafından atanan yönetilen kimliklerin koleksiyonunu içeren bir "identity" özelliği eklersiniz. Veri kaynağı oluşturulurken yalnızca bir kullanıcı tarafından atanan yönetilen kimlik sağlanmalıdır. "userAssignedIdentities" yazacak şekilde ayarlayın.

Aşağıda, Veri Kaynağı Oluşturma veya Güncelleştirme REST API'sini kullanarak dizin oluşturucu veri kaynağı nesnesi oluşturma örneği verilmiştir:

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

Dizini oluşturma

Dizin, bir belgedeki alanları, öznitelikleri ve arama deneyimini şekillendiren diğer yapıları belirtir.

Aşağıda aranabilir bir alanı olan Dizin REST API'sini Oluştur çağrısı verilmiştir booktitle :

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

Dizin oluşturucu oluşturma

Dizin oluşturucu bir veri kaynağını hedef arama dizinine bağlar ve veri yenilemeyi otomatikleştirmek için bir zamanlama sağlar. Dizin ve veri kaynağı oluşturulduktan sonra dizin oluşturucuyu oluşturmaya ve çalıştırmaya hazır olursunuz. Dizin oluşturucu başarılı olursa, bağlantı söz dizimi ve rol atamaları geçerli olur.

Aşağıda , NoSQL için Azure Cosmos DB dizin oluşturucu tanımına sahip bir Dizin Oluşturucu REST API'sini oluşturma çağrısı verilmiştir. dizin oluşturucu, isteği gönderdiğinizde çalışır.

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

Sorun giderme

Azure Cosmos DB hesap anahtarlarınızı kısa süre önce döndürdüyseniz, yönetilen kimlik bağlantı dizesi çalışması için 15 dakikaya kadar beklemeniz gerekir.

Azure Cosmos DB hesabının erişiminin belirli ağlarla sınırlı olup olmadığını denetleyin. Herhangi bir kısıtlama olmadan bağlantıyı deneyerek güvenlik duvarı sorunlarını eleyebilirsiniz.

Ayrıca bkz.