Mengelola layanan Pencarian Azure AI Anda menggunakan REST API

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Pelajari cara membuat dan mengonfigurasi layanan Pencarian Azure AI menggunakan REST API Management. 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.

Semua REST API Manajemen memiliki contoh. Jika tugas tidak tercakup dalam artikel ini, lihat referensi API sebagai gantinya.

Tips

Jika Anda menggunakan CURL untuk memanggil REST API Manajemen, pastikan Anda mengatur header jenis konten ke aplikasi/json: -H "Content-Type: application/json". Atau, Anda dapat menggunakan --JSON bendera jika Anda ingin menyematkan JSON.

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 dalam langganan Azure Anda.

    Panggilan REST API Manajemen diautentikasi melalui Microsoft Entra ID. 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 perintah shell untuk CLI Azure.

    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. Dapatkan 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 tile Ekstensi.

  2. Cari klien REST dan pilih Instal.

    Cuplikan layar perintah 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. Kalau tidak, daftar tersebut akan kosong, tetapi selama kode HTTP menunjukkan 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 = 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 Pencarian Azure AI hanya tersedia untuk layanan baru. Untuk menghindari pembuatan ulang layanan dan menambahkan 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}}

Mengubah tingkat 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 sku properti dan hostingMode . 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"
        }
    }

Konfigurasi akses berbasis peran untuk lintasan data

Berlaku untuk: Kontributor Data Indeks Pencarian, Pembaca Data Indeks Pencarian, 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 menindaklanjuti permintaan kedua, kali ini diatur disableLocalAuth ke 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 biaya tambahan sebesar 10% untuk lapis tagihan. Untuk informasi selengkapnya, 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 tetap selama masa pakai 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 beban kerja yang mendorong data ke sumber daya eksternal

Pencarian Azure AI writes ke sumber data eksternal saat memperbarui penyimpanan pengetahuan, menyimpan status dari sesi debug, atau menyimpan pengayaan dalam cache. 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}}

Buat kunci API kueri

### 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 buat indeks atau kueri indeks menggunakan portal Azure, REST API, atau Azure SDK.

  • Terakhir diperbarui pada