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

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. Anda dapat secara opsional berlakukan akses berbasis peran sebagai satu-satunya metode autentikasi untuk koneksi data dengan mengatur disableLocalAuth ke true untuk Azure Cosmos DB akun NoSQL Anda.

Prasyarat

• Buat identitas terkelola untuk layanan pencarian Anda.

Keterbatasan

• Pengindeks yang tersambung ke Azure Cosmos DB untuk Gremlin dan MongoDB (saat ini dalam pratinjau) hanya mendukung pendekatan legacy.

Pendekatan yang didukung untuk autentikasi identitas terkelola

Pencarian Azure AI mendukung dua mekanisme untuk terhubung ke Azure Cosmos DB menggunakan identitas terkelola.

• Pendekatan legacy mengharuskan mengkonfigurasi identitas terkelola untuk memiliki izin pembaca pada rencana kontrol akun Azure Cosmos DB target. Pencarian Azure AI menggunakan identitas tersebut untuk mengambil kunci akun Cosmos DB di latar belakang untuk mengakses data. Pendekatan ini tidak akan berfungsi jika akun Cosmos DB memiliki "disableLocalAuth": true.

• Pendekatan modern memerlukan konfigurasi peran identitas terkelola yang sesuai pada kontrol dan bidang data akun Azure Cosmos DB target. Pencarian Azure AI kemudian akan meminta token akses untuk mengakses data di akun Cosmos DB. Pendekatan ini berfungsi bahkan jika akun Cosmos DB memiliki "disableLocalAuth": true.

Pengindeks yang terhubung ke Azure Cosmos DB untuk NoSQL mendukung pendekatan legacy dan pendekatan modern - pendekatan modern direkomendasikan.

Menyambungkan ke Azure Cosmos DB untuk NoSQL

Bagian ini menguraikan langkah-langkah untuk mengonfigurasi koneksi ke Azure Cosmos DB untuk NoSQL melalui pendekatan modern.

Mengonfigurasi penetapan peran lapisan kontrol

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

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

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, tunggu beberapa menit.

8. Pilih identitas dan simpan penetapan peran.

Untuk informasi selengkapnya, lihat Gunakan kontrol akses berbasis peran pada control plane dengan Azure Cosmos DB untuk NoSQL.

Mengonfigurasi penetapan peran bidang data

Identitas terkelola perlu menetapkan peran untuk dibaca dari sarana data akun Cosmos DB. ID Objek (utama) untuk sistem layanan pencarian/identitas yang ditetapkan pengguna dapat ditemukan dari tab "Identitas" layanan pencarian. Langkah ini hanya dapat dilakukan melalui Azure CLI saat ini.

Atur variabel:

$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)

Tentukan penetapan peran untuk identitas yang ditetapkan sistem:

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

Untuk informasi selengkapnya, lihat Gunakan kontrol akses berbasis peran bidang data dengan Azure Cosmos DB untuk NoSQL

Mengonfigurasi definisi sumber data

Setelah mengonfigurasi both bidang kontrol dan penetapan peran bidang data pada Azure Cosmos DB untuk akun NoSQL, Anda dapat menyiapkan koneksi ke sana 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.

REST API, portal Azure, dan .NET SDK mendukung penggunaan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.

Menyambungkan melalui identitas yang ditetapkan sistem

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.

Berikut adalah contoh menggunakan Rest API Buat Sumber Data yang menjalankan pendekatan modern .

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]" }
}

Terhubung melalui identitas yang ditetapkan pengguna

Anda perlu menambahkan properti "identitas" ke definisi sumber data, tempat Anda menentukan identitas tertentu (dari beberapa yang dapat ditetapkan ke layanan pencarian), yang akan digunakan untuk menyambungkan ke akun Azure Cosmos DB.

Berikut adalah contoh menggunakan identitas yang ditetapkan pengguna melalui pendekatan modern .

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]" 
    }
}

Terhubung dengan Azure Cosmos DB untuk Gremlin/MongoDB (pratinjau)

Bagian ini menguraikan langkah-langkah untuk mengonfigurasi koneksi ke Azure Cosmos DB untuk Gremlin/Mongo melalui pendekatan legacy.

Mengonfigurasi penetapan peran lapisan kontrol

Ikuti langkah yang sama seperti sebelumnya untuk menetapkan peran yang sesuai pada sarana kontrol Azure Cosmos DB untuk Gremlin/MongoDB.

Mengatur string koneksi

• Untuk koleksi MongoDB, tambahkan "ApiKind=MongoDb" ke string koneksi dan gunakan pratinjau REST API.
• Untuk grafik Gremlin, tambahkan "ApiKind=Gremlin" ke string koneksi dan gunakan pratinjau REST API.
• Untuk kedua jenisnya, hanya pendekatan legacy yang didukung - yaitu, IdentityAuthType=AccountKey atau menghilangkannya sepenuhnya adalah satu-satunya string koneksi yang valid.

Berikut adalah contoh untuk menyambungkan ke koleksi MongoDB menggunakan identitas yang ditetapkan sistem melalui REST API

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
}

Berikut adalah contoh untuk menyambungkan ke grafik Gremlin menggunakan identitas yang ditetapkan pengguna.

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]" 
    }
}

Jalankan pengindeks untuk memverifikasi izin

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.

Memecahkan masalah koneksi

• Untuk Azure Cosmos DB untuk NoSQL, periksa apakah akun memiliki aksesnya dibatasi untuk memilih jaringan. Anda dapat mengesampingkan masalah firewall apa pun dengan mencoba koneksi tanpa batasan. Lihat akses Indexer ke konten yang dilindungi oleh keamanan jaringan Azure untuk informasi selengkapnya

• Untuk Azure Cosmos DB untuk NoSQL, jika pengindeks gagal karena masalah autentikasi, pastikan bahwa penetapan peran telah dilakukan baik pada lintasan kontrol maupun lintasan data akun Cosmos DB.

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

Lihat juga

• Pengindeksan menggunakan Azure Cosmos DB untuk NoSQL
• Pengindeksan melalui Azure Cosmos DB untuk MongoDB (pratinjau)
• Pengindeksan melalui Azure Cosmos DB untuk Apache Gremlin (pratinjau)