Azure Cosmos DB'ye yönetilen kimlik ile bağlanma (Azure Yapay Zeka Arama)

Bu makalede, bağlantı dizesi kimlik bilgilerini sağlamak yerine yönetilen kimlik kullanarak bir 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'daki verilere erişmek için Azure rol atamaları gerektirir. İsteğe bağlı olarak, NoSQL hesabınız için Azure Cosmos DB'de 'i disableLocalAuth olarak ayarlayarak, rol tabanlı erişimi veri bağlantıları için tek kimlik doğrulama yöntemi olarak true.

Önkoşullar

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

Sınırlama

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

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

Azure Yapay Zeka Arama, yönetilen kimlik kullanarak Azure Cosmos DB bağlanmak için iki mekanizmayı destekler.

• legacy 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 Yapay Zeka Arama 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üzlemindeki uygun rollerin yapılandırılmasını gerektirir. Azure Yapay Zeka Arama 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 bağlanan dizin oluşturucular hem legacy hem de modern yaklaşımını destekler- modern yaklaşımı önerilir.

NoSQL için Azure Cosmos DB bağlanma

Bu bölümde, modern yaklaşımıyla NoSQL için Azure Cosmos DB bağlanmayı yapılandırma adımları açıklanmıştır.

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

1. Azure portalında oturum açın ve NoSQL hesabı için Cosmos DB'nizi 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. Eğer bir tane yoksa, lütfen Aramayı yönetilen kimlik kullanacak şekilde yapılandırma sayfasına bakınız. Zaten bir tane oluşturduysanız ancak henüz etkin değilse, 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ğe, Cosmos DB hesabının veri düzleminden okumak için bir rol atanması 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-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --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 $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

Daha fazla bilgi için bkz. NoSQL

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

Azure Cosmos DB NoSQL 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, veri kaynağının bağlantı dizesinde sistem tarafından atanan yönetilen kimlik veya kullanıcı tarafından atanan yönetilen kimliğin nasıl belirtileceği açıklamaktadır. Yönetilen kimlik makalesinde daha fazla bağlantı dizesi örnekleri bulabilirsiniz.

REST API, Azure portalı ve .NET SDK sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği kullanma desteği.

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=2026-04-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];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=2026-04-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];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 bağlanma (önizleme)

Bu bölümde, legacy yaklaşımı aracılığıyla Gremlin/Mongo için Azure Cosmos DB 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 denetim düzleminde uygun rolleri atamak için önceki adımları izleyin.

Bağlantı dizesini ayarlayın

• MongoDB koleksiyonları için bağlantı dizesi "ApiKind=MongoDb" ekleyin ve önizleme REST API'sini kullanın.
• Gremlin grafikleri için bağlantı dizesine "ApiKind=Gremlin" ekleyin ve bir önizleme REST API'si kullanın.
• Her iki tür için de yalnızca legacy yaklaşımı desteklenir; yani IdentityAuthType=AccountKey veya tamamen çıkararak 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=2026-08-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=2026-08-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 Azure Cosmos DB için hesabın belirli ağlara erişiminin kısıtlanıp kısıtlanmadığını denetleyin. Herhangi bir kısıtlama olmadan bağlantıyı deneyerek güvenlik duvarı sorunlarını eleyebilirsiniz. Daha fazla bilgi için Azure ağ güvenliği tarafından korunan içeriğe Indexer erişimine bakın

• NoSQL için Azure Cosmos DB'de dizin oluşturucu kimlik doğrulama sorunları nedeniyle başarısız olursa, rol atamalarının Cosmos DB hesabının hem denetim düzleminde hem de 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ı dizesinin çalışması için 15 dakikaya kadar beklemeniz gerekir.

Ayrıca bkz.

• Azure Cosmos DB aracılığıyla NoSQL için indeksleme
• MongoDB için Azure Cosmos DB aracılığıyla dizin oluşturma (önizleme)
• Azure Cosmos DB for Apache Gremlin aracılığıyla dizin oluşturma (önizleme)