Mengelola layanan Pencarian Azure AI Anda dengan REST API

• Portal
• PowerShell
• Azure CLI
• 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 peringkat 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.

1. Buka shell perintah untuk Azure CLI.

2. Masuk ke langganan Azure Anda.

   az login
   

3. Dapatkan ID penyewa dan ID langganan. Jika Anda memiliki beberapa penyewa atau langganan, pastikan Anda menggunakan yang benar.

   az account show
   

4. Mendapatkan token akses.

   az account get-access-token --query accessToken --output tsv
   

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.

1. Mulai Visual Studio Code dan pilih petak ekstensi .

2. Cari klien REST dan pilih Instal.

   

3. Buka atau buat file baru bernama dengan .rest ekstensi file atau .http .

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

5. 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}}
   

6. 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": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

Menonaktifkan peringkat semantik

Meskipun peringkat semantik tidak diaktifkan secara default, Anda dapat mengunci fitur di tingkat layanan.

### disable semantic ranking
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 

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, REST API, atau Azure SDK.

• Membuat indeks Pencarian Azure AI di portal Azure
• Menyiapkan pengindeks untuk memuat data dari layanan lain
• Mengkueri indeks Pencarian Azure AI menggunakan Penjelajah pencarian di portal Azure
• Cara menggunakan Azure AI Search di .NET