Bagikan melalui

Menyambungkan ke Azure Cosmos DB menggunakan identitas terkelola (Azure AI Search)

  • Artikel

Artikel ini menjelaskan cara menyiapkan koneksi pengindeks ke database Azure Cosmos DB menggunakan identitas terkelola alih-alih memberikan kredensial di string koneksi.'

Anda dapat menggunakan identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna. Identitas terkelola adalah login Microsoft Entra dan memerlukan penetapan peran Azure untuk mengakses data di Azure Cosmos DB.

Prasyarat

Batasan

Dukungan pengindeks untuk Azure Cosmos DB untuk Koleksi Gremlin dan MongoDB saat ini dalam pratinjau. Saat ini, batasan pratinjau mengharuskan Azure AI Search untuk tersambung menggunakan kunci. Anda masih dapat menyiapkan identitas terkelola dan penetapan peran, tetapi Azure AI Search hanya akan menggunakan penetapan peran untuk mendapatkan kunci untuk koneksi. Batasan ini berarti Anda tidak dapat mengonfigurasi pendekatan berbasis peran jika pengindeks Anda tersambung ke Gremlin atau MongoDB.

Membuat penetapan peran di Azure Cosmos DB

  1. Masuk ke portal Azure dan temukan akun Cosmos DB for NoSQL Anda.

  2. Pilih Kontrol Akses (IAM) .

  3. Pilih Tambahkan lalu pilih Penetapan peran.

  4. Dari daftar peran fungsi pekerjaan, pilih Pembaca Akun Cosmos DB.

  5. Pilih Selanjutnya.

  6. Pilih Identitas terkelola lalu pilih Anggota.

  7. Filter menurut identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna. Anda akan melihat identitas terkelola yang sebelumnya Anda buat untuk layanan pencarian Anda. Jika Anda tidak memilikinya, lihat Mengonfigurasi pencarian untuk menggunakan identitas terkelola. Jika Anda sudah menyiapkannya tetapi tidak tersedia, beri beberapa menit.

  8. Pilih identitas dan simpan penetapan peran.

Untuk informasi selengkapnya, lihat Mengonfigurasi kontrol akses berbasis peran dengan ID Microsoft Entra untuk akun Azure Cosmos DB Anda.

Menentukan identitas terkelola dalam string koneksi

Setelah memiliki penetapan peran, Anda dapat menyiapkan koneksi ke Azure Cosmos DB untuk NoSQL yang beroperasi di bawah peran tersebut.

Pengindeks menggunakan objek sumber data untuk koneksi ke sumber data eksternal. Bagian ini menjelaskan cara menentukan identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna pada sumber data string koneksi. Anda dapat menemukan contoh string koneksi lainnya di artikel identitas terkelola.

Tip

Anda dapat membuat koneksi sumber data ke CosmosDB di portal Azure, menentukan sistem atau identitas terkelola yang ditetapkan pengguna, lalu melihat definisi JSON untuk melihat bagaimana string koneksi diformulasikan.

Identitas terkelola yang ditetapkan sistem

REST API,portal Microsoft Azure, dan .NET SDK mendukung string koneksi identitas terkelola.

Saat Anda terhubung dengan identitas terkelola yang ditetapkan sistem, satu-satunya perubahan pada definisi sumber data adalah format properti "kredensial". Berikan nama database dan ResourceId yang tidak memiliki kunci akun atau kata sandi. ResourceId harus menyertakan ID langganan Azure Cosmos DB, grup sumber daya, dan nama akun Azure Cosmos DB.

  • Untuk koleksi SQL, string koneksi tidak memerlukan "ApiKind".
  • Untuk koleksi SQL, tambahkan "IdentityAuthType=AccessToken" jika akses berbasis peran diberlakukan sebagai satu-satunya metode autentikasi. Ini tidak berlaku untuk koleksi MongoDB dan Gremlin.
  • Untuk koleksi MongoDB, tambahkan "ApiKind=MongoDb" ke string koneksi dan gunakan REST API pratinjau.
  • Untuk grafik Gremlin, tambahkan "ApiKind=Gremlin" ke string koneksi dan gunakan PRATINJAU REST API.

Berikut adalah contoh cara membuat sumber data untuk mengindeks data dari akun Cosmos DB menggunakan Rest API Buat Sumber Data dan identitas terkelola string koneksi. Format string koneksi identitas terkelola sama untuk REST API, .NET SDK, dan portal Microsoft Azure.

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

 
}

Identitas terkelola yang ditetapkan pengguna

Saat Anda menyambungkan dengan identitas terkelola yang ditetapkan pengguna, ada dua perubahan pada definisi sumber data:

  • Pertama, format properti "kredensial" adalah nama database dan ResourceId yang tidak memiliki kunci akun atau kata sandi. ResourceId harus menyertakan ID langganan Azure Cosmos DB, grup sumber daya, dan nama akun Azure Cosmos DB.

    • Untuk koleksi SQL, string koneksi tidak memerlukan "ApiKind".
    • Untuk koleksi SQL, tambahkan "IdentityAuthType=AccessToken" jika akses berbasis peran diberlakukan sebagai satu-satunya metode autentikasi. Ini tidak berlaku untuk koleksi MongoDB dan Gremlin.
    • Untuk koleksi MongoDB, tambahkan "ApiKind=MongoDb" ke string koneksi
    • Untuk grafik Gremlin, tambahkan "ApiKind=Gremlin" ke string koneksi.

  • Kedua, Anda menambahkan properti "identitas" yang berisi kumpulan identitas terkelola yang ditetapkan pengguna. Hanya satu identitas terkelola yang ditetapkan pengguna yang harus disediakan saat membuat sumber data. Atur ke ketik "userAssignedIdentities".

Berikut adalah contoh cara membuat objek sumber data pengindeks menggunakan REST API.

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
}

Informasi koneksi dan izin pada layanan jarak jauh divalidasi pada waktu proses selama eksekusi pengindeks. Jika pengindeks berhasil, sintaks koneksi dan penetapan peran valid. Untuk informasi selengkapnya, lihat Menjalankan atau mengatur ulang pengindeks, keterampilan, atau dokumen.

Pemecahan Masalah

Untuk Azure Cosmos DB for NoSQL, periksa apakah akun memiliki aksesnya dibatasi untuk memilih jaringan. Anda dapat mengesampingkan masalah firewall apa pun dengan mencoba koneksi tanpa batasan.

Untuk Gremlin atau MongoDB, jika Anda baru saja memutar kunci akun Azure Cosmos DB, Anda perlu menunggu hingga 15 menit agar identitas terkelola string koneksi berfungsi.

Lihat juga