Mengelola layanan Pencarian Azure AI Anda dengan REST API

Artikel
12/10/2024

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.

Bagikan melalui