Mengelola layanan Pencarian Azure AI Anda dengan REST API
Dalam artikel ini, pelajari cara membuat dan mengonfigurasi azure AI layanan Pencarian menggunakan REST API Manajemen. Hanya REST API Manajemen yang dijamin untuk menyediakan akses awal ke fitur pratinjau.
REST API Manajemen tersedia dalam versi stabil dan pratinjau. Pastikan untuk mengatur versi API pratinjau jika Anda mengakses fitur pratinjau.
- Membuat atau memperbarui layanan
- Mengaktifkan kontrol akses berbasis peran Azure untuk bidang data
- Menerapkan kebijakan kunci yang dikelola pelanggan
- Menonaktifkan ranker semantik
- Menonaktifkan beban kerja yang mendorong data ke sumber daya eksternal
- Membuat kunci kueri
- Meregenerasi kunci admin
- Mencantumkan koneksi titik akhir privat
- Mencantumkan operasi pencarian
- Menghapus layanan pencarian
Semua REST API Manajemen memiliki contoh. Jika tugas tidak tercakup dalam artikel ini, lihat referensi API sebagai gantinya.
Prasyarat
Langganan Azure - Buat langganan gratis.
Visual Studio Code dengan klien REST.
Azure CLI digunakan untuk mendapatkan token akses. Anda harus menjadi pemilik atau administrator di langganan Azure Anda.
Mendapatkan token akses
Panggilan REST API manajemen diautentikasi melalui ID Microsoft Entra. Anda perlu memberikan token akses pada permintaan, bersama dengan izin untuk membuat dan mengonfigurasi sumber daya.
Anda dapat menggunakan Azure CLI atau Azure PowerShell untuk membuat token akses.
Buka shell perintah untuk Azure CLI.
Masuk ke langganan Azure Anda.
az login
Dapatkan ID penyewa dan ID langganan. Jika Anda memiliki beberapa penyewa atau langganan, pastikan Anda menggunakan yang benar.
az account show
Mendapatkan token akses.
az account get-access-token --query accessToken --output tsv
Anda harus memiliki ID penyewa, ID langganan, dan token pembawa. Anda akan menempelkan nilai-nilai ini ke .rest
dalam file atau .http
yang Anda buat di langkah berikutnya.
Menyiapkan Visual Studio Code
Jika Anda tidak terbiasa dengan klien REST untuk Visual Studio Code, bagian ini menyertakan penyiapan sehingga Anda dapat menyelesaikan tugas dalam mulai cepat ini.
Mulai Visual Studio Code dan pilih petak ekstensi .
Cari klien REST dan pilih Instal.
Buka atau buat file baru bernama dengan
.rest
ekstensi file atau.http
.Berikan variabel untuk nilai yang Anda ambil di langkah sebelumnya.
@tenantId = PASTE-YOUR-TENANT-ID-HERE @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE @token = PASTE-YOUR-TOKEN-HERE
Pastikan sesi beroperasi dengan mencantumkan layanan pencarian di langganan Anda.
### List search services GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01 Content-type: application/json Authorization: Bearer {{token}}
Pilih Kirim Permintaan. Respons akan muncul di panel yang berdekatan. Jika Anda memiliki layanan pencarian yang sudah ada, layanan tersebut akan dicantumkan. Jika tidak, daftar kosong, tetapi selama kode HTTP adalah 200 OK, Anda siap untuk langkah-langkah berikutnya.
HTTP/1.1 200 OK Cache-Control: no-cache Pragma: no-cache Content-Length: 22068 Content-Type: application/json; charset=utf-8 Expires: -1 x-ms-ratelimit-remaining-subscription-reads: 11999 x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c Strict-Transport-Security: max-age=31536000; includeSubDomains X-Content-Type-Options: nosniff X-Cache: CONFIG_NOCACHE X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z Date: Thu, 14 Mar 2024 01:20:52 GMT Connection: close { "value": [ . . . ] }
Membuat atau memperbarui layanan
Membuat atau memperbarui layanan pencarian di bawah langganan saat ini. Contoh ini menggunakan variabel untuk nama dan wilayah layanan pencarian, yang belum ditentukan. Berikan nama secara langsung, atau tambahkan variabel baru ke koleksi.
### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "North Central US",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "default"
}
}
Membuat layanan S3HD
Untuk membuat layanan S3HD , gunakan kombinasi sku
properti dan hostingMode
. Atur sku
ke standard3
dan "hostingMode" ke HighDensity
.
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "{{region}}",
"sku": {
"name": "standard3"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "HighDensity"
}
}
Mengonfigurasi akses berbasis peran untuk bidang data
Berlaku pada: Kontributor Data Indeks Pencarian, Pembaca Data Indeks, Kontributor Layanan Pencarian
Pada langkah ini, konfigurasikan layanan pencarian Anda untuk mengenali header otorisasi pada permintaan data yang menyediakan token akses OAuth2.
Untuk menggunakan kontrol akses berbasis peran untuk operasi sarana data, atur authOptions
ke aadOrApiKey
lalu kirim permintaan.
Untuk menggunakan kontrol akses berbasis peran secara eksklusif, nonaktifkan autentikasi kunci API dengan menindaklanjuti permintaan kedua, kali ini diatur disableLocalAuth
ke true.
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"disableLocalAuth": false,
"authOptions": {
"aadOrApiKey": {
"aadAuthFailureMode": "http401WithBearerChallenge"
}
}
}
}
Menerapkan kebijakan kunci yang dikelola pelanggan
Jika Anda menggunakan enkripsi yang dikelola pelanggan, Anda dapat mengaktifkan "encryptionWithCMK" dengan "penegakan" diatur ke "Diaktifkan" jika Anda ingin layanan pencarian melaporkan status kepatuhannya.
Saat Anda mengaktifkan kebijakan ini, setiap panggilan REST yang membuat objek yang berisi data sensitif, seperti string koneksi dalam sumber data, akan gagal jika kunci enkripsi tidak disediakan:"Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Menonaktifkan ranker semantik
Meskipun peringkat semantik tidak diaktifkan secara default, Anda dapat mengunci fitur di tingkat layanan untuk kepastian yang lebih besar, fitur tersebut tidak dapat digunakan.
### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"semanticSearch": "Disabled"
}
}
Menonaktifkan beban kerja yang mendorong data ke sumber daya eksternal
Azure AI Search menulis ke sumber data eksternal saat memperbarui penyimpanan pengetahuan, menyimpan status sesi debug, atau pengayaan penembolokan. Contoh berikut menonaktifkan beban kerja ini di tingkat layanan.
### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"publicNetworkAccess": "Disabled"
}
}
Menghapus layanan pencarian
### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Mencantumkan kunci API admin
### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Meregenerasi kunci API admin
Anda hanya dapat meregenerasi satu kunci API admin pada satu waktu.
### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Membuat kunci API kueri
### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Mencantumkan koneksi titik akhir privat
### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Mencantumkan operasi pencarian
### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Langkah berikutnya
Setelah layanan pencarian dikonfigurasi, langkah berikutnya termasuk membuat indeks atau mengkueri indeks menggunakan portal Azure, REST API, atau Azure SDK.