Mengelola layanan Pencarian Azure AI Anda menggunakan REST API

Pelajari cara membuat dan mengonfigurasi layanan Pencarian Azure AI menggunakan API REST 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
• Meningkatkan layanan
• Mengubah tingkat penetapan harga
• Mengonfigurasi kontrol akses berbasis peran untuk bidang data
• Mengonfigurasi komputasi rahasia
• Mengaktifkan kontrol akses berbasis peran Azure untuk bidang data
• Menerapkan kebijakan kunci yang dikelola pelanggan
• Menonaktifkan pengurut 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

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Visual Studio Code dengan klien REST.

• Azure CLI untuk mendapatkan token akses, seperti yang dijelaskan dalam langkah-langkah berikut. Anda harus menjadi pemilik atau administrator di langganan Azure Anda.

  Panggilan REST API manajemen diautentikasi melalui ID Microsoft Entra. Anda harus memberikan token akses pada permintaan dan izin untuk membuat dan mengonfigurasi sumber daya. Selain Azure CLI, Anda dapat menggunakan Azure PowerShell untuk membuat token akses.

  1. Buka jendela perintah untuk Azure CLI.

  2. Masuk ke langganan Azure Anda. Jika Anda memiliki beberapa penyewa atau langganan, pastikan Anda memilih yang benar.

     az login
     

  3. Dapatkan ID penyewa dan ID langganan.

     az account show
     

  4. 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 dalam file .rest 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 artikel ini.

1. Mulai Visual Studio Code dan pilih papan Extensions.

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.

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-YOUR-TOKEN-HERE
   

5. Pastikan sesi beroperasi dengan mencantumkan layanan pencarian di langganan Anda.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         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 sebaliknya, daftar kosong, tetapi selama kode HTTP menunjukkan 200 OK, Anda siap untuk melanjutkan ke 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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

Meningkatkan layanan

Beberapa kemampuan Azure AI Search hanya tersedia untuk layanan baru. Untuk menghindari rekreasi layanan dan membawa kemampuan ini ke layanan yang ada, Anda mungkin dapat meningkatkan layanan Anda.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Ubah kategori harga

Jika Anda membutuhkan lebih banyak atau kurang kapasitas, Anda dapat beralih ke tingkat harga yang berbeda. Saat ini, Anda hanya dapat beralih antara tingkat Dasar dan Standar (S1, S2, dan S3). sku Gunakan properti untuk menentukan tingkat baru.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Membuat layanan S3HD

Untuk membuat layanan S3HD, gunakan kombinasi dari sku dan hostingMode properti. Atur sku ke standard3 dan "hostingMode" ke HighDensity.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 data plane

Berlaku pada: Kontributor Data Indeks Pencarian, Pembaca Data Indeks, Kontributor Layanan Pencarian

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 melakukan permintaan kedua, kali ini mengatur disableLocalAuth menjadi true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Mengonfigurasi komputasi rahasia

Komputasi rahasia adalah jenis komputasi opsional untuk perlindungan penggunaan data. Saat dikonfigurasi, layanan pencarian Anda disebarkan pada VM rahasia (DCasv5 atau DCesv5) alih-alih VM standar. Jenis komputasi ini juga dikenakan surcharge sebesar 10% untuk tingkatan yang bisa ditagihkan. Untuk informasi lebih lanjut, lihat halaman harga.

Untuk penggunaan harian, komputasi rahasia tidak diperlukan. Kami hanya merekomendasikan jenis komputasi ini untuk persyaratan peraturan, kepatuhan, atau keamanan yang ketat. Untuk informasi selengkapnya, lihat Kasus penggunaan komputasi rahasia.

Jenis komputasi ditetapkan untuk masa operasional layanan pencarian Anda. Untuk mengonfigurasi komputasi rahasia secara permanen, atur properti ke computeTypeconfidential pada layanan baru.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

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

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Menonaktifkan peringkat semantik

Peringkat semantik diaktifkan secara default pada paket gratis yang memungkinkan hingga 1.000 permintaan per bulan tanpa biaya. Anda dapat mengunci fitur di tingkat layanan untuk mencegah penggunaan.

### Disable semantic ranker
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 menyimpan sementara pengayaan. Contoh berikut menonaktifkan beban kerja ini di tingkat layanan.

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Menghapus layanan pencarian

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Mencantumkan kunci API admin

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Menghasilkan ulang kunci API admin

Anda hanya dapat meregenerasi satu kunci API admin pada satu waktu.

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Membuat kunci kueri API

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Mencantumkan koneksi titik akhir privat

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Daftar operasi pencarian

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Langkah berikutnya

Setelah layanan pencarian dikonfigurasi, langkah Anda berikutnya termasuk membuat indeks atau mengkueri indeks menggunakan portal Microsoft Azure, 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