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

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. İsteğe bağlı olarak, NoSQL için Azure 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.

Önkoşullar

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

Yönetilen kimlik kimlik doğrulaması için desteklenen yaklaşımlar

Azure AI Search, yönetilen kimlik kullanarak Azure Cosmos DB'ye bağlanmak için iki mekanizmayı destekler.

• Eski yaklaşım, yönetilen kimliğin hedef Azure Cosmos DB hesabının denetim düzleminde okuyucu izinlerine sahip olacak şekilde yapılandırılmasını gerektirir. Azure AI Search, verilere erişmek için cosmos DB hesabının hesap anahtarlarını arka planda getirmek için bu kimliği kullanır. Cosmos DB hesabında "disableLocalAuth": truevarsa bu yaklaşım çalışmaz.

• Modern yaklaşım, yönetilen kimliğin hedef Azure Cosmos DB hesabının denetim ve veri düzleminde uygun rollerin yapılandırılmasını gerektirir. Azure AI Search daha sonra Cosmos DB hesabındaki verilere erişmek için bir erişim belirteci isteyecektir. Cosmos DB hesabında "disableLocalAuth": trueolsa bile bu yaklaşım çalışır.

NoSQL için Azure Cosmos DB'ye bağlanan dizin oluşturucular hem eski hem de modern yaklaşımı destekler. Modern yaklaşım kesinlikle önerilir.

Sınırlamalar

• Gremlin ve MongoDB için Azure Cosmos DB'ye bağlanan dizin oluşturucular (şu anda önizleme aşamasındadır) yalnızca eski yaklaşımı destekler.

NoSQL için Azure Cosmos DB'ye bağlanma

Bu bölümde, modern yaklaşım aracılığıyla NoSQL için Azure Cosmos DB'ye bağlanmayı yapılandırma adımları özetlenmiştir.

Denetim düzlemi rol atamalarını yapılandırma

1. Azure portalında oturum açın ve NoSQL için Cosmos DB hesabınızı bulun.

2. Erişim denetimi (IAM) öğesini seçin.

3. Ekle'yi ve ardından Rol ataması'ı seçin.

4. İş işlevi rolleri listesinden Cosmos DB Hesap Okuyucusu'na tıklayın.

5. İleri'yi seçin.

6. Yönetilen kimlik'i ve ardından Üyeler'i seçin.

7. 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.

8. Kimliği seçin ve rol atamasını kaydedin.

Daha fazla bilgi için bkz . NoSQL için Azure Cosmos DB ile denetim düzlemi rol tabanlı erişim denetimini kullanma.

Veri düzlemi rol atamalarını yapılandırma

Yönetilen kimliğin Cosmos DB hesabının veri düzleminden okumak için bir rol ataması gerekir. Arama hizmetinin sistem/kullanıcı tarafından atanan kimliğinin Nesne (sorumlu) kimliği, arama hizmetinin "Kimlik" sekmesinde bulunabilir. Bu adım şu anda yalnızca Azure CLI aracılığıyla gerçekleştirilebilir.

Değişkenleri ayarlama:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user 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

Daha fazla bilgi için bkz . NoSQL için Azure Cosmos DB ile veri düzlemi rol tabanlı erişim denetimini kullanma

Veri kaynağı tanımını yapılandırma

NoSQL için Azure Cosmos DB hesabında hem denetim düzlemi hem de veri düzlemi rol atamalarını yapılandırdıktan sonra, bu rol altında çalışan 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.

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

Sistem tarafından atanan kimlik aracılığıyla bağlanma

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.

Burada, modern yaklaşımı kullanan Veri Kaynağı Oluşturma REST API'sini kullanan bir örnek verilmiştir.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Kullanıcı tarafından atanan kimlik aracılığıyla bağlanma

Azure Cosmos DB hesabına bağlanmak için kullanılacak belirli kimliği (arama hizmetine atanabilecek birkaç kimlikten) belirttiğiniz veri kaynağı tanımına bir "identity" özelliği eklemeniz gerekir.

Aşağıda modern yaklaşım aracılığıyla kullanıcı tarafından atanan kimliğin kullanıldığı bir örnek verilmişti.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Gremlin/MongoDB için Azure Cosmos DB'ye bağlanma (önizleme)

Bu bölümde, eski yaklaşım aracılığıyla Gremlin/Mongo için Azure Cosmos DB'ye bağlanmayı yapılandırma adımları özetlenmiştir.

Denetim düzlemi rol atamalarını yapılandırma

Gremlin/MongoDB için Azure Cosmos DB'nin denetim düzleminde uygun rolleri atamak için önceki adımları izleyin.

Bağlantı dizesini ayarlama

• 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.
• Her iki tür için de yalnızca eski yaklaşım desteklenir; yani IdentityAuthType=AccountKey tamamen atlanması tek geçerli bağlantı dizesi.

Rest API aracılığıyla sistem tarafından atanan kimliği kullanarak MongoDB koleksiyonlarına bağlanma örneği aşağıda verilmiştir

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "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=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Aşağıda, kullanıcı tarafından atanan kimliği kullanarak Gremlin graflarına bağlanmaya yönelik bir örnek verilmiştir.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "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=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

İzinleri doğrulamak için dizin oluşturucuyu çalıştırın

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.

Bağlantı sorunlarını 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. Daha fazla bilgi için Bkz. Azure ağ güvenliği tarafından korunan içeriğe Dizin Oluşturucu erişimi

• NoSQL için Azure Cosmos DB için dizin oluşturucu kimlik doğrulama sorunları nedeniyle başarısız olursa rol atamalarının hem denetim düzleminde hem de Cosmos DB hesabının veri düzleminde yapıldığından emin olun.

• 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.

Ayrıca bkz.

• NoSQL için Azure Cosmos DB aracılığıyla dizin oluşturma
• MongoDB için Azure Cosmos DB aracılığıyla dizin oluşturma
• Apache Gremlin için Azure Cosmos DB aracılığıyla dizin oluşturma