Menyiapkan koneksi pengindeks ke Azure Cosmos DB melalui identitas terkelola

  • 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 (pratinjau). Identitas terkelola adalah login Microsoft Entra dan memerlukan penetapan peran Azure untuk mengakses data di Azure Cosmos DB.

Prasyarat

  • Buat identitas terkelola untuk layanan pencarian Anda.

  • Tetapkan peran Pembaca Akun Cosmos DB ke identitas terkelola layanan pencarian. Peran ini memberikan kemampuan untuk membaca data akun Azure Cosmos DB. Untuk informasi selengkapnya tentang penetapan peran di Cosmos DB, lihat Mengonfigurasi kontrol akses berbasis peran ke data.

  • Penetapan Peran Bidang Data: Ikuti Penetapan Peran bidang data untuk mengetahui lebih lanjut.

  • Contoh untuk penetapan peran sarana data baca-saja:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Penetapan peran untuk identitas yang ditetapkan sistem:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

  • Untuk Cosmos DB for NoSQL, Anda dapat secara opsional menerapkan akses berbasis peran sebagai satu-satunya metode autentikasi untuk koneksi data dengan mengatur disableLocalAuth ke true untuk akun Cosmos DB Anda.

  • Untuk Koleksi Gremlin dan MongoDB: Dukungan pengindeks saat ini dalam pratinjau. Saat ini, ada batasan pratinjau yang 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 menggunakan Pencarian dengan identitas terkelola untuk terhubung ke Azure Cosmos DB.

  • Anda harus terbiasa dengan konsep dan konfigurasi pengindeks.

Membuat sumber data

Buat sumber data dan berikan identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna (pratinjau) di string koneksi.

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". Anda akan memberikan 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 penyimpanan 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=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Identitas terkelola yang ditetapkan pengguna (pratinjau)

REST API pratinjau 2021-04-30 mendukung koneksi berdasarkan 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 pratinjau Buat atau Perbarui REST API Sumber Data:

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];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
}

Membuat indeks

Indeks menentukan bidang dalam dokumen, atribut, dan konstruksi lain yang membentuk pengalaman pencarian.

Berikut adalah panggilan Buat INDEKS REST API dengan bidang yang dapat dicari booktitle :

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

Membuat pemberi indeks

Pengindeks menyambungkan sumber data dengan indeks pencarian target dan menyediakan jadwal untuk mengotomatiskan refresh data. Setelah indeks dan sumber data dibuat, Anda siap untuk membuat dan menjalankan pengindeks. Jika pengindeks berhasil, sintaks koneksi dan penetapan peran valid.

Berikut adalah panggilan Buat REST API Pengindeks dengan definisi pengindeks Azure Cosmos DB for NoSQL. Pengindeks berjalan saat Anda mengirimkan permintaan.

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

Pemecahan Masalah

Jika Anda baru-baru ini memutar kunci akun Azure Cosmos DB, Anda harus menunggu hingga 15 menit agar identitas terkelola string koneksi berfungsi.

Periksa untuk melihat apakah akun Azure Cosmos DB memiliki aksesnya dibatasi untuk memilih jaringan. Anda dapat mengesampingkan masalah firewall apa pun dengan mencoba koneksi tanpa batasan.

Lihat juga