Yönetilen kimlik kullanarak Azure Cosmos DB'ye bağlanma (Azure AI Search)

Makale
09/01/2024

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 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.
NoSQL için Azure Cosmos DB. İsteğe bağlı olarak Cosmos DB hesabınız için olarak ayarlayarak disableLocalAuth true veri bağlantıları için tek kimlik doğrulama yöntemi olarak rol tabanlı erişimi zorunlu kılabilirsiniz.

Sınırlamalar

Gremlin ve MongoDB Koleksiyonları için Azure Cosmos DB için dizin oluşturucu desteği şu anda önizleme aşamasındadır. Şu anda bir önizleme sınırlaması için Azure AI Search'in anahtarları kullanarak bağlanması gerekir. 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 Gremlin veya MongoDB'ye bağlanıyorsa rol tabanlı bir yaklaşım yapılandıramamanız anlamına gelir.

Azure portalında oturum açın ve NoSQL için Cosmos DB hesabınızı bulun.
Erişim denetimi (IAM) öğesini seçin.
Ekle'yi ve ardından Rol ataması'ı seçin.
İş işlevi rolleri listesinden Cosmos DB Hesap Okuyucusu'na tıklayın.
İleri'yi seçin.
Yönetilen kimlik'i ve ardından Üyeler'i seçin.
Sistem tarafından atanan yönetilen kimliklere veya kullanıcı tarafından atanan yönetilen kimliklere göre filtreleyin. Arama hizmetiniz için daha önce oluşturduğunuz yönetilen kimliği görmeniz gerekir. Aramanız yoksa bkz . Aramayı yönetilen kimlik kullanacak şekilde yapılandırma. Zaten bir tane ayarladıysanız ancak kullanılamıyorsa birkaç dakika bekleyin.
Kimliği seçin ve rol atamasını kaydedin.

Daha fazla bilgi için bkz . Azure Cosmos DB hesabınız için Microsoft Entra Id ile rol tabanlı erişim denetimini yapılandırma.

Değişkenleri ayarlama:

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

Sistem tarafından atanan kimlik için bir rol ataması tanımlayın:

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

bağlantı dizesi yönetilen kimlik belirtme

Rol atamanız olduktan sonra, bu rol altında çalışan NoSQL için Azure Cosmos DB'ye bir bağlantı ayarlayabilirsiniz.

Dizin oluşturucular, dış veri kaynağına bağlantılar için bir veri kaynağı nesnesi kullanır. Bu bölümde, bir veri kaynağı bağlantı dizesi sistem tarafından atanan yönetilen kimliğin veya kullanıcı tarafından atanan yönetilen kimliğin nasıl belirtileceğini açıklanmaktadır. Daha fazla bağlantı dizesi örneği yönetilen kimlik makalesinde bulabilirsiniz.

İpucu

Azure portalında CosmosDB'ye bir veri kaynağı bağlantısı oluşturabilir, sistem veya kullanıcı tarafından atanan yönetilen kimliği belirtebilir ve ardından bağlantı dizesi nasıl formüle edileceğini görmek için JSON tanımını görüntüleyebilirsiniz.

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. Hesap anahtarı veya parolası olmayan bir veritabanı adı ve ResourceId girin. 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 Cosmos DB 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=2024-07-01
{
    "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;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Kullanıcı tarafından atanan yönetilen kimlik

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.

REST API kullanarak dizin oluşturucu veri kaynağı nesnesinin nasıl oluşturulacağını gösteren bir örnek aşağıda verilmiştir.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01

{
    "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;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
}

Uzak hizmet üzerindeki bağlantı bilgileri ve izinler, dizin oluşturucu yürütmesi sırasında çalışma zamanında doğrulanır. Dizin oluşturucu başarılı olursa, bağlantı söz dizimi ve rol atamaları geçerli olur. Daha fazla bilgi için bkz . Dizin oluşturucuları, becerileri veya belgeleri çalıştırma veya sıfırlama.

Sorun giderme

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

Gremlin veya MongoDB için Azure Cosmos DB hesap anahtarlarınızı yakın zamanda döndürdüyseniz yönetilen kimlik bağlantı dizesi çalışması için 15 dakikaya kadar beklemeniz gerekir.

Aracılığıyla paylaş