Aracılığıyla paylaş

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

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

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 Cosmos DB'de rol ataması oluşturma

  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 . Azure Cosmos DB hesabınız için Microsoft Entra Id ile rol tabanlı erişim denetimini yapılandırma.

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=2023-11-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=2023-11-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.

Ayrıca bkz.