Membuat Peta Sinonim (Azure AI Search REST API)

  • Artikel

Di Azure AI Search, peta sinonim berisi daftar aturan untuk memperluas atau menulis ulang kueri pencarian ke istilah yang setara.

Anda dapat menggunakan POST atau PUT pada permintaan. Untuk salah satu dari keduanya, dokumen JSON dalam isi permintaan menyediakan definisi objek.

POST https://[service name].search.windows.net/synonymmaps?api-version=[api-version]      
  Content-Type: application/json  
  api-key: [admin key]

Atau, Anda dapat menggunakan PUT dan menentukan nama peta sinonim pada URI.

PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

HTTPS diperlukan untuk semua permintaan layanan. Jika peta sinonim tidak ada, peta sinonim akan dibuat. Jika sudah ada, itu diperbarui ke definisi baru.

Catatan

Jumlah maksimum peta sinonim yang dapat Anda buat bervariasi menurut tingkat harga. Untuk informasi selengkapnya, lihat Batas layanan.

Parameter URI

Parameter Deskripsi
nama layanan Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
nama peta sinonim Diperlukan pada URI jika menggunakan PUT. Nama harus huruf kecil, dimulai dengan huruf atau angka, tidak memiliki garis miring atau titik, dan kurang dari 128 karakter. Setelah memulai nama dengan huruf atau angka, sisa nama dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut.
versi-api Wajib diisi. Versi stabil saat ini adalah api-version=2020-06-30. Lihat Versi API untuk versi lainnya.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang Deskripsi
Jenis-Konten Wajib diisi. Atur titik akhir ini ke application/json
api-key Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Membuat permintaan harus menyertakan header yang api-key diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci untuk detailnya.

Isi Permintaan

Isi permintaan berisi definisi peta sinonim, yang mencakup format peta sinonim dan daftar aturan dalam format yang ditentukan.

JSON berikut adalah representasi tingkat tinggi dari bagian utama definisi.

{   
    "name" : (optional on PUT; required on POST) "Name of the synonym map",  
    "format" : (required) "Only Apache Solr format ('solr') is currently supported.",
    "synonyms" : (required) "Synonym rules separated by the new line ('\n') character.",
    "encryptionKey":(optional) { See below for details } 
}

Permintaan berisi properti berikut:

Properti Deskripsi
nama Wajib diisi. Nama peta sinonim. Nama peta sinonim hanya boleh berisi huruf kecil, digit, atau tanda hubung, tidak boleh dimulai atau diakhir dengan tanda hubung dan dibatasi hingga 128 karakter.
format Wajib diisi. Hanya format Apache Solr (solr) yang saat ini didukung.
sinonim Wajib diisi. Aturan sinonim dipisahkan oleh karakter baris baru ('\n').
encryptionKey Opsional. Digunakan untuk mengenkripsi peta sinonim, dengan kunci Anda sendiri, dikelola di Key Vault Azure Anda. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01.

Bagian encryptionKey berisi yang ditentukan keyVaultKeyName pengguna (diperlukan), yang dihasilkan keyVaultKeyVersion sistem (diperlukan), dan keyVaultUri menyediakan kunci (diperlukan, juga disebut sebagai nama DNS). Contoh URI mungkin "https://my-keyvault-name.vault.azure.net".

Secara opsional, Anda dapat menentukan accessCredentials apakah Anda tidak menggunakan identitas sistem terkelola. Properti yang accessCredentials disertakan applicationId (ID Aplikasi Azure Active Directory yang diberikan izin akses ke Key Vault Azure tertentu), dan applicationSecret (kunci autentikasi aplikasi Azure AD yang ditentukan). Contoh di bagian berikutnya mengilustrasikan sintaks.

Respons

Untuk permintaan yang berhasil: 201 Dibuat.

Contoh

Contoh: Daftar sinonim dengan pemetaan yang setara dan eksplisit.

Aturan pemetaan yang setara mencantumkan istilah atau frasa yang setara yang dipisahkan dengan koma ("AS, Amerika Serikat, Amerika Serikat Amerika"). Aturan memperluas pencarian ke semua istilah atau frasa yang setara. Misalnya, dokumen pencarian yang berisi USA akan cocok pada kueri yang berisi istilah USA atau frasa "United States", atau "United States of America".

Pemetaan eksplisit ditandai dengan panah => ("AS, A.S., A.S., Amerika Serikat, Amerika Serikat Amerika => AS"). Saat ditentukan, urutan istilah kueri pencarian yang cocok dengan sisi => kiri akan diganti dengan alternatif di sisi kanan. Mengingat aturan, kueri U.S. pencarian atau "United States" semuanya akan ditulis ulang menjadi USA. Pemetaan eksplisit hanya berlaku dalam arah yang ditentukan dan tidak menulis ulang kueri USA ke "United States" dalam kasus ini. Perhatikan bahwa "Amerika Serikat" adalah kueri frasa yang diapit kutipan. Jika Anda menginginkan kecocokan pada seluruh frasa, string kueri harus diapit dalam tanda kutip ganda. Jika tidak, setiap istilah, "United" dan "States", dievaluasi secara terpisah.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA"
}

Contoh: Kunci enkripsi

Kunci enkripsi adalah kunci yang dikelola pelanggan yang digunakan untuk enkripsi tambahan. Untuk informasi selengkapnya, lihat Enkripsi menggunakan kunci yang dikelola pelanggan di Azure Key Vault.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
          "applicationId": "Azure AD Application ID that was granted access permissions to your specified Azure Key Vault",
          "applicationSecret": "Authentication key of the specified Azure AD application)"
      }
  }
}

Lihat juga