Buat atau Perbarui Indeks (Pratinjau REST API)

Artikel
07/26/2022
25 menit untuk membaca

Versi API: 2021-04-30-Preview, 2020-06-30-Preview

Penting

Pratinjau 30-04-2021 menambahkan:

"semanticConfiguration" digunakan untuk pencakupan peringkat semantik ke bidang tertentu.
"identitas", di bawah "encryptionKey", digunakan untuk mengambil kunci enkripsi yang dikelola pelanggan dari Azure Key Vault menggunakan identitas terkelola yang ditetapkan pengguna.

Pratinjau 30-06-2020 menambahkan:

"normalizer", digunakan untuk ketidakpekaan huruf besar/kecil pada pengurutan dan filter.

Indeks menentukan skema indeks, termasuk koleksi bidang (nama bidang, jenis data, dan atribut), tetapi juga konstruksi tambahan (saran, profil penilaian, dan konfigurasi CORS) yang menentukan perilaku pencarian lainnya.

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

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

Untuk permintaan pembaruan, gunakan PUT dan tentukan nama indeks pada URI.

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

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

Membuat indeks menetapkan skema dan metadata. Mengisi indeks adalah operasi terpisah. Untuk langkah ini, Anda dapat menggunakan pengindeks (lihat Operasi pengindeks, tersedia untuk sumber data yang didukung) atau Tambahkan, Perbarui, atau Hapus Dokumen. Jumlah maksimum indeks yang dapat Anda buat bervariasi menurut tingkat harga. Dalam setiap indeks, ada batasan pada masing-masing elemen. Untuk informasi selengkapnya, lihat Batas layanan untuk Azure Cognitive Search.

Memperbarui indeks yang ada harus menyertakan definisi skema lengkap, termasuk definisi asli yang ingin Anda pertahankan. Secara umum, pola terbaik untuk pembaruan adalah mengambil definisi indeks dengan GET, memodifikasinya, lalu memperbaruinya dengan PUT.

Karena indeks yang ada berisi konten, banyak modifikasi indeks memerlukan penurunan dan pembangunan ulang indeks. Perubahan skema berikut adalah pengecualian untuk aturan ini:

Menambahkan bidang baru
Menambahkan atau mengubah profil penilaian
Menambahkan atau mengubah konfigurasi semantik
Mengubah opsi CORS
Mengubah bidang yang sudah ada dengan salah satu dari tiga modifikasi berikut:
- Tampilkan atau sembunyikan bidang (retrievable: true | false)
- Mengubah penganalisis yang digunakan pada waktu kueri (searchAnalyzer)
- Menambahkan atau mengedit synonymMap yang digunakan pada waktu kueri (synonymMaps)

Untuk membuat salah satu perubahan skema di atas pada indeks yang ada, tentukan nama indeks pada URI permintaan, lalu sertakan definisi indeks yang sepenuhnya ditentukan dengan elemen baru atau yang diubah.

Saat bidang baru ditambahkan, semua dokumen yang ada dalam indeks secara otomatis memiliki nilai null untuk bidang tersebut. Tidak ada ruang penyimpanan tambahan yang digunakan sampai salah satu dari dua hal terjadi: nilai disediakan untuk bidang baru (menggunakan penggabungan), atau dokumen baru ditambahkan.

Updates memiliki batasan serupasuggester: bidang baru dapat ditambahkan ke suggester bidang pada saat yang sama ditambahkan, tetapi bidang yang ada tidak dapat dihapus dari atau ditambahkan ke suggesters tanpa pembangunan ulang indeks.

Updates ke penganalisis, tokenizer, filter token, atau filter karakter tidak diizinkan. Yang baru dapat dibuat dengan perubahan yang Anda inginkan, tetapi Anda harus membuat indeks offline saat menambahkan definisi penganalisis baru. allowIndexDowntime Mengatur bendera ke true dalam permintaan pembaruan indeks akan membuat indeks offline:

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Operasi ini membuat indeks Anda offline setidaknya selama beberapa detik, yang berarti permintaan pengindeksan dan kueri akan gagal sampai indeks kembali online dan siap menangani permintaan.

Parameter URI

Parameter	Deskripsi
nama layanan	Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
nama indeks	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. Tanda hubung tidak bisa berturut-turut.
versi-api	Wajib diisi. Versi saat ini adalah `api-version=2021-04-30-Preview`. Lihat Versi API untuk versi lainnya.
allowIndexDowntime	Opsional. Salah secara default. Atur ke true untuk pembaruan tertentu, seperti menambahkan atau memodifikasi penganalisis, tokenizer, filter token, filter karakter, atau properti kesamaan. Indeks diambil offline selama durasi pembaruan, biasanya tidak lebih dari beberapa detik.

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	Wajib diisi. `api-key` digunakan untuk mengautentikasi permintaan ke layanan Pencarian Anda. Ini adalah nilai string, unik untuk layanan Anda. Membuat permintaan harus menyertakan header yang `api-key` diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Anda dapat menemukan kunci API di dasbor layanan pencarian di portal Azure.

Isi Permintaan

Isi permintaan berisi definisi skema, yang mencakup daftar bidang data dalam dokumen yang akan diumpankan ke dalam indeks ini.

JSON berikut adalah representasi tingkat tinggi dari bagian utama definisi.

{  
  "name": (optional on PUT; required on POST) "Name of the index",
  "description": (optional) "Description of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ] (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
    }
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "semantic": (optional) { },
  "normalizers":(optional) [ ... ],
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}

Permintaan berisi properti berikut:

Properti	Deskripsi
nama	Wajib diisi. Nama indeks. Nama indeks hanya boleh berisi huruf kecil, digit, atau tanda hubung, tidak boleh dimulai atau diakhapi dengan tanda hubung dan dibatasi hingga 128 karakter.
deskripsi	Deskripsi opsional.
Bidang	Kumpulan bidang untuk indeks ini, di mana setiap bidang memiliki nama, jenis data yang didukung yang sesuai dengan Model Data Entitas (EDM), dan atribut yang menentukan tindakan yang diizinkan pada bidang tersebut. Koleksi bidang harus memiliki satu bidang jenis `Edm.String` dengan "kunci" diatur ke "true". Bidang ini mewakili pengidentifikasi unik, terkadang disebut ID dokumen, untuk setiap dokumen yang disimpan dengan indeks.
Kesamaan	Opsional. Untuk layanan yang dibuat sebelum 15 Juli 2020, atur properti ini untuk menggunakan algoritma peringkat BM25. Nilai yang valid meliputi `"#Microsoft.Azure.Search.ClassicSimilarity"` atau `"#Microsoft.Azure.Search.BM25Similarity"`. Untuk informasi selengkapnya, lihat Algoritma peringkat di Azure Cognitive Search.
pemberi saran	Menentukan konstruksi yang menyimpan awalan untuk pencocokan pada kueri parsial seperti lengkapi otomatis dan saran.
scoringProfiles	Opsional. Digunakan untuk peringkat skor pencarian kustom. Anda dapat menjadikan profil kustom Anda sebagai default dengan mengatur `defaultScoringProfile`, dipanggil setiap kali profil kustom tidak ditentukan secara eksplisit pada string kueri. Untuk informasi selengkapnya, lihat Menambahkan profil penilaian ke indeks pencarian.
Semantik	Opsional. Menentukan parameter indeks pencarian yang memengaruhi kemampuan pencarian semantik. Konfigurasi semantik diperlukan untuk kueri semantik. Untuk informasi selengkapnya, lihat Membuat kueri semantik.
normalizer	Opsional. Menormalkan urutan leksikografis string, menghasilkan output pengurutan dan pemfilteran yang tidak peka huruf besar/kecil.
penganalisis, charFilters, tokenizer, tokenFilters	Opsional. Tentukan bagian indeks ini jika Anda menentukan penganalisis kustom. Secara default, bagian ini null.
defaultScoringProfile	Nama profil penilaian kustom yang menimpa perilaku penilaian default.
corsOptions	Opsional. Digunakan untuk kueri lintas asal ke indeks Anda.
encryptionKey	Opsional. Digunakan untuk enkripsi tambahan indeks, melalui kunci enkripsi (CMK) yang dikelola pelanggan di Azure Key Vault. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01.

Respons

Untuk permintaan pembuatan yang berhasil, Anda akan melihat kode status "201 Dibuat". Secara default, isi respons akan berisi JSON untuk definisi indeks yang dibuat. Namun, jika header Permintaan pilihan diatur ke return=minimal, isi respons akan kosong, dan kode status keberhasilan akan menjadi "204 Tidak Ada Konten" alih-alih "201 Dibuat". Ini benar terlepas dari apakah PUT atau POST digunakan untuk membuat indeks.

Untuk permintaan pembaruan yang berhasil, Anda akan melihat "204 Tanpa Konten". Secara default isi respons akan kosong. Namun, jika Prefer header permintaan diatur ke return=representation, isi respons akan berisi JSON untuk definisi indeks yang diperbarui. Dalam hal ini, kode status keberhasilan akan menjadi "200 OK".

Contoh

Contoh: Skema indeks dengan bidang sederhana dan kompleks

Contoh pertama menunjukkan skema indeks lengkap dengan bidang sederhana dan kompleks. Setidaknya satu bidang string harus memiliki "kunci" yang diatur ke true.

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true, "normalizer": "lowercase" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" }
        ]
    }
  ],
  "suggesters": [ ],
  "analyzers": [ ],
  "normalizers": [ ],
  "encryptionKey": [ ]
}

Contoh: Pemberi Saran

Definisi pemberi saran harus menentukan bidang string "dapat dicari" dan "dapat diambil" (di REST API, semua bidang sederhana secara "retrievable": true default). Setelah pemberi saran ditentukan, Anda dapat mereferensikannya berdasarkan nama pada permintaan kueri yang menggunakan API Saran atau API Lengkapi Otomatis, tergantung pada apakah Anda ingin mengembalikan kecocokan atau sisa istilah kueri.

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "suggesters": [
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": ["HotelName", "Category", "Tags"]  
    } 
  ]
}

Contoh: Penganalisis dan normalizer

Penganalisis dan normalizer direferensikan pada definisi bidang dan dapat ditentukan sebelumnya atau kustom. Jika Anda menggunakan penganalisis atau normalizer kustom, Anda akan menentukannya dalam indeks di bagian "penganalisis" dan "normalizer".

Contoh berikut mengilustrasikan penganalisis dan normalizer kustom untuk "Tag". Ini juga menunjukkan normalizer yang telah ditentukan sebelumnya (standar) dan penganalisis (en.microsoft) untuk "HotelName" dan "Description", masing-masing.

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false, "normalizer": standard  },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft"},
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ],
  "normalizers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
      "name": "tagsNormalizer",
      "tokenFilters": [ "asciifolding", "lowercase" ]
    }
  ]
}

Contoh: Kesamaan untuk relevansi pencarian

Properti ini mengatur algoritma peringkat yang digunakan untuk membuat skor relevansi dalam hasil pencarian kueri pencarian teks lengkap. Dalam layanan yang dibuat setelah 15 Juli 2020, properti ini diabaikan karena algoritma kesamaan selalu BM25. Untuk layanan yang sudah ada yang dibuat sebelum 15 Juli 2020, Anda dapat memilih BM25 dengan mengatur konstruksi ini sebagai berikut:

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

Contoh: Opsi CORS

JavaScript sisi klien tidak dapat memanggil API apa pun secara default karena browser akan mencegah semua permintaan lintas asal. Untuk mengizinkan kueri lintas asal ke indeks Anda, aktifkan CORS (Berbagi sumber daya lintas asal (Wikipedia)) dengan mengatur corsOptions atribut . Untuk alasan keamanan, hanya API kueri yang mendukung CORS.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

Contoh: Kunci enkripsi dengan kredensial akses

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": "hotels",  
    "fields": [ omitted for brevity ],
    "suggesters": [ omitted for brevity ],
    "analyzers": [ omitted for brevity ],
    "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": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified AAD application)"}
      }
}

Contoh: Kunci enkripsi dengan identitas terkelola

Anda dapat mengautentikasi ke Azure Key Vault menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna (pratinjau). Dalam hal ini, hilangkan kredensial akses, atau atur ke null. Contoh berikut menunjukkan identitas terkelola yang ditetapkan pengguna. Untuk menggunakan identitas terkelola yang ditetapkan sistem, hilangkan kredensial dan identitas akses. Selama identitas sistem layanan pencarian Anda memiliki izin di Azure Key Vault, permintaan koneksi akan berhasil.

{
    "name": "hotels",  
    "fields": [ omitted for brevity ],
    "suggesters": [ omitted for brevity ],
    "analyzers": [ omitted for brevity ],
    "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": null,
        "identity" : { 
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
      }
}

Contoh: Profil Penilaian

Profil penilaian adalah bagian dari skema yang menentukan perilaku penilaian kustom yang memungkinkan Anda memengaruhi dokumen mana yang tampak lebih tinggi dalam hasil pencarian. Profil penilaian terdiri dari bobot dan fungsi lapangan. Untuk menggunakannya, Anda menentukan profil menurut nama pada string kueri. Untuk informasi selengkapnya, lihat Menambahkan profil penilaian ke indeks pencarian (Azure Cognitive Search REST API) untuk detailnya.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

Contoh: Konfigurasi Semantik

Konfigurasi semantik adalah bagian dari definisi indeks yang digunakan untuk mengonfigurasi bidang mana yang akan digunakan oleh pencarian semantik untuk peringkat, keterangan, sorotan, dan jawaban. Untuk menggunakan pencarian semantik, Anda harus menentukan nama konfigurasi semantik pada waktu kueri. Untuk informasi selengkapnya, lihat Membuat kueri semantik.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "my-semantic-config",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "hotelName"
               },
           "prioritizedContentFields": [
             {
               "fieldName": "description"
             },
             {
               "fieldName": "description_fr"
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "tags"
             },
             {
               "fieldName": "category"
             }
           ]
         }
       }
     ]
   }
}

Definisi

Tautan	Deskripsi
corsOptions	Mencantumkan domain atau asal yang akan diberikan ke indeks Anda.
encryptionKey	Mengonfigurasi koneksi ke Azure Key Vault untuk enkripsi yang dikelola pelanggan.
Bidang	Mengatur definisi dan atribut bidang dalam indeks pencarian.
normalizer	Mengonfigurasi normalizer kustom. Menormalkan urutan leksikografis string, menghasilkan output pengurutan, faset, dan pemfilteran yang tidak peka huruf besar/kecil.
Semantik	Mengonfigurasi bidang yang digunakan oleh pencarian semantik untuk peringkat, keterangan, sorotan, dan jawaban.
pemberi saran	Mengonfigurasi penyimpanan awalan internal untuk pencocokan pada kueri parsial seperti lengkapi otomatis dan saran.

corsOptions

JavaScript sisi klien tidak dapat memanggil API apa pun secara default karena browser akan mencegah semua permintaan lintas asal. Untuk mengizinkan kueri lintas asal ke indeks Anda, aktifkan CORS (Berbagi Sumber Daya Lintas Asal) dengan mengatur atribut "corsOptions". Untuk alasan keamanan, hanya API kueri yang mendukung CORS.

Atribut Deskripsi

allowedOrigins Wajib diisi. Daftar asal yang dibatasi koma yang akan diberikan akses ke indeks Anda, di mana setiap asal biasanya dari formulir protocol://<-qualified-domain-name>:<port> (meskipun <port> sering dihilangkan). Ini berarti bahwa setiap kode JavaScript yang disajikan dari asal tersebut akan diizinkan untuk mengkueri indeks Anda (dengan asumsi kode tersebut menyediakan kunci API yang valid). Jika Anda ingin mengizinkan akses ke semua asal, tentukan * sebagai satu item dalam array "allowedOrigins". Ini tidak disarankan untuk produksi, tetapi mungkin berguna untuk pengembangan atau penelusuran kesalahan.

maxAgeInSeconds Opsional. Browser menggunakan nilai ini untuk menentukan durasi (dalam detik) untuk menyimpan respons preflight CORS. Nilai harus bilangan bulat non-negatif. Semakin besar nilai ini, semakin baik performanya, tetapi semakin lama waktu yang diperlukan untuk menerapkan perubahan kebijakan CORS. Jika tidak disetel, durasi default 5 menit akan digunakan.

Atribut	Deskripsi
allowedOrigins	Wajib diisi. Daftar asal yang dibatasi koma yang akan diberikan akses ke indeks Anda, di mana setiap asal biasanya dari formulir protocol://<-qualified-domain-name>:<port> (meskipun <port> sering dihilangkan). Ini berarti bahwa setiap kode JavaScript yang disajikan dari asal tersebut akan diizinkan untuk mengkueri indeks Anda (dengan asumsi kode tersebut menyediakan kunci API yang valid). Jika Anda ingin mengizinkan akses ke semua asal, tentukan `*` sebagai satu item dalam array "allowedOrigins". Ini tidak disarankan untuk produksi, tetapi mungkin berguna untuk pengembangan atau penelusuran kesalahan.
maxAgeInSeconds	Opsional. Browser menggunakan nilai ini untuk menentukan durasi (dalam detik) untuk menyimpan respons preflight CORS. Nilai harus bilangan bulat non-negatif. Semakin besar nilai ini, semakin baik performanya, tetapi semakin lama waktu yang diperlukan untuk menerapkan perubahan kebijakan CORS. Jika tidak disetel, durasi default 5 menit akan digunakan.

encryptionKey

Mengonfigurasi koneksi ke Azure Key Vault untuk kunci enkripsi (CMK) yang dikelola pelanggan tambahan. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01.

Koneksi ke brankas kunci harus diautentikasi. Anda dapat menggunakan "accessCredentials" atau identitas terkelola untuk tujuan ini.

Identitas terkelola dapat berupa sistem atau ditetapkan pengguna (pratinjau). Jika layanan pencarian memiliki identitas terkelola yang ditetapkan sistem dan penetapan peran yang memberikan akses baca ke brankas kunci, Anda dapat menghilangkan "identitas" dan "accessCredentials", dan permintaan akan mengautentikasi menggunakan identitas terkelola. Jika layanan pencarian memiliki identitas dan penetapan peran yang ditetapkan pengguna, atur properti "identitas" ke ID sumber daya identitas tersebut.

Atribut	Deskripsi
keyVaultKeyName	Wajib diisi. Nama kunci Azure Key Vault yang digunakan untuk enkripsi.
keyVaultKeyVersion	Wajib diisi. Versi kunci Key Vault Azure.
keyVaultUri	Wajib diisi. URI Azure Key Vault, juga disebut sebagai nama DNS, yang menyediakan kuncinya. Contoh URI mungkin `https://my-keyvault-name.vault.azure.net`
accessCredentials	Opsional. Hilangkan properti ini jika Anda menggunakan identitas terkelola. Jika tidak, properti "accessCredentials" meliputi: "applicationId" (ID Aplikasi Azure Active Directory yang memiliki izin akses ke Azure Key Vault yang Anda tentukan). "applicationSecret" (kunci autentikasi aplikasi Azure AD yang ditentukan).
identity	Opsional kecuali Anda menggunakan identitas terkelola yang ditetapkan pengguna untuk koneksi layanan pencarian ke Azure Key Vault. Formatnya adalah `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`.

fields

Berisi informasi tentang atribut yang diatur pada bidang pencarian saat membuat indeks.

Atribut	Deskripsi
nama	Wajib diisi. Mengatur nama bidang, yang harus unik dalam kumpulan bidang indeks atau bidang induk.
jenis	Wajib diisi. Mengatur jenis data untuk bidang . Bidang bisa sederhana atau kompleks. Bidang sederhana adalah jenis primitif, seperti `Edm.String` untuk teks atau `Edm.Int32` untuk bilangan bulat. Bidang kompleks dapat memiliki sub-bidang yang sederhana atau kompleks. Ini memungkinkan Anda untuk memodelkan objek dan array objek, yang pada gilirannya memungkinkan Anda mengunggah sebagian besar struktur objek JSON ke indeks Anda. Lihat Jenis data yang didukung untuk daftar lengkap jenis yang didukung.
kunci	Wajib diisi. Atur atribut ini ke true untuk menunjuk bahwa nilai bidang secara unik mengidentifikasi dokumen dalam indeks. Panjang maksimum nilai dalam bidang kunci adalah 1024 karakter. Tepat satu bidang tingkat atas di setiap indeks harus dipilih sebagai bidang kunci dan harus berjenis `Edm.String`. Defaultnya adalah `false` untuk bidang sederhana dan `null` untuk bidang kompleks. Bidang kunci dapat digunakan untuk mencari dokumen secara langsung dan memperbarui atau menghapus dokumen tertentu. Nilai bidang kunci ditangani dengan cara yang peka huruf besar/kecil saat mencari atau mengindeks dokumen. Lihat Dokumen Pencarian dan Tambahkan, Perbarui, atau Hapus Dokumen untuk detailnya.
dapat diambil	Menunjukkan apakah bidang dapat dikembalikan dalam hasil pencarian. Atur atribut ini ke `false` jika Anda ingin menggunakan bidang (misalnya, margin) sebagai filter, pengurutan, atau mekanisme penilaian tetapi tidak ingin bidang terlihat oleh pengguna akhir. Atribut ini harus `true` untuk bidang kunci, dan harus `null` untuk bidang kompleks. Atribut ini dapat diubah pada bidang yang ada. Pengaturan yang dapat diambil `true` tidak menyebabkan peningkatan persyaratan penyimpanan indeks. Defaultnya adalah `true` untuk bidang sederhana dan `null` untuk bidang kompleks.
dapat dicari	Menunjukkan apakah bidang dapat dicari teks lengkap dan dapat direferensikan dalam kueri pencarian. Ini berarti akan menjalani analisis leksikal seperti pemecahan kata selama pengindeksan. Jika Anda mengatur bidang yang dapat dicari ke nilai seperti "Hari Cerah", secara internal bidang tersebut akan dinormalisasi dan dibagi menjadi token individu "cerah" dan "hari". Ini memungkinkan pencarian teks lengkap untuk istilah-istilah ini. Bidang jenis `Edm.String` atau `Collection(Edm.String)` dapat dicari secara default. Atribut ini harus `false` untuk bidang sederhana dari jenis data non-string lainnya, dan harus `null` untuk bidang kompleks. Bidang yang dapat dicari menggunakan ruang ekstra dalam indeks Anda karena Azure Cognitive Search akan memproses konten bidang tersebut dan mengaturnya dalam struktur data tambahan untuk pencarian berkinerja. Jika Anda ingin menghemat ruang dalam indeks Dan Anda tidak memerlukan bidang untuk disertakan dalam pencarian, atur dapat dicari ke `false`. Lihat Cara kerja pencarian teks lengkap di Azure Cognitive Search untuk detailnya.
dapat difilter	Menunjukkan apakah akan mengaktifkan bidang yang akan direferensikan dalam `$filter` kueri. Dapat difilter berbeda dari yang dapat dicari dalam bagaimana string ditangani. Bidang jenis `Edm.String` atau `Collection(Edm.String)` yang dapat difilter tidak mengalami analisis leksikal, sehingga perbandingan hanya untuk kecocokan yang tepat. Misalnya, jika Anda mengatur bidang `f` seperti itu ke "Hari cerah", `$filter=f eq 'sunny'` tidak akan menemukan kecocokan, tetapi `$filter=f eq 'Sunny day'` akan. Atribut ini harus `null` untuk bidang kompleks. Defaultnya adalah `true` untuk bidang sederhana dan `null` untuk bidang kompleks. Untuk mengurangi ukuran indeks, atur atribut ini ke `false` pada bidang yang tidak akan Anda filter.
bisa diurutkan	Menunjukkan apakah akan mengaktifkan bidang yang akan direferensikan dalam `$orderby` ekspresi. Secara default Azure Cognitive Search mengurutkan hasil menurut skor, tetapi dalam banyak pengalaman pengguna akan ingin mengurutkan menurut bidang dalam dokumen. Bidang sederhana hanya dapat diurutkan jika bernilai tunggal (memiliki nilai tunggal dalam cakupan dokumen induk). Bidang koleksi sederhana tidak dapat diurutkan, karena bidang tersebut multinilai. Sub-bidang sederhana dari koleksi kompleks juga multinilai, dan oleh karena itu tidak dapat diurutkan. Ini benar apakah itu bidang induk langsung, atau bidang leluhur, itulah koleksi yang kompleks. Bidang kompleks tidak dapat diurutkan dan atribut yang dapat diurutkan harus `null` untuk bidang tersebut. Default untuk dapat diurutkan adalah `true` untuk bidang sederhana bernilai tunggal, `false` untuk bidang sederhana multinilai, dan `null` untuk bidang kompleks.
facetable	Menunjukkan apakah akan mengaktifkan bidang yang akan direferensikan dalam kueri faset. Biasanya digunakan dalam presentasi hasil pencarian yang mencakup hitungan menurut kategori (misalnya, mencari kamera digital dan melihat hit berdasarkan merek, berdasarkan megapiksel, berdasarkan harga, dan sebagainya). Atribut ini harus `null` untuk bidang kompleks. Bidang bertipe `Edm.GeographyPoint` atau `Collection(Edm.GeographyPoint)` tidak dapat difasetkan. Defaultnya adalah `true` untuk semua bidang sederhana lainnya. Untuk mengurangi ukuran indeks, atur atribut ini ke `false` pada bidang yang tidak akan Anda fasetkan.
Analyzer	Mengatur penganalisis leksikal untuk tokenisasi string selama operasi pengindeksan dan kueri. Nilai yang valid untuk properti ini termasuk penganalisis bahasa, penganalisis bawaan, dan penganalisis kustom. Defaultnya adalah `standard.lucene`. Atribut ini hanya dapat digunakan dengan bidang yang dapat dicari, dan tidak dapat diatur bersama dengan searchAnalyzer atau indexAnalyzer. Setelah penganalisis dipilih dan bidang dibuat dalam indeks, itu tidak dapat diubah untuk bidang . Harus `null` untuk bidang kompleks.
searchAnalyzer	Atur properti ini bersama dengan indexAnalyzer untuk menentukan penganalisis leksikal yang berbeda untuk pengindeksan dan kueri. Jika Anda menggunakan properti ini, atur penganalisis ke `null` dan pastikan indexAnalyzer diatur ke nilai yang diizinkan. Nilai yang valid untuk properti ini termasuk penganalisis bawaan dan penganalisis kustom. Atribut ini hanya dapat digunakan dengan bidang yang dapat dicari. Penganalisis pencarian dapat diperbarui pada bidang yang ada karena hanya digunakan pada waktu kueri. Harus `null` untuk bidang kompleks.
indexAnalyzer	Atur properti ini bersama dengan searchAnalyzer untuk menentukan penganalisis leksikal yang berbeda untuk pengindeksan dan kueri. Jika Anda menggunakan properti ini, atur penganalisis ke `null` dan pastikan searchAnalyzer diatur ke nilai yang diizinkan. Nilai yang valid untuk properti ini termasuk penganalisis bawaan dan penganalisis kustom. Atribut ini hanya dapat digunakan dengan bidang yang dapat dicari. Setelah penganalisis indeks dipilih, penganalisis tidak dapat diubah untuk bidang . Harus `null` untuk bidang kompleks.
Normalizer	Mengatur normalizer untuk pemfilteran, pengurutan, dan operasi faset. Ini bisa menjadi nama normalizer yang telah ditentukan sebelumnya atau normalizer kustom yang ditentukan dalam indeks. Defaultnya adalah `null`, yang menghasilkan kecocokan persis pada teks verbatim dan tidak dianalisis. Atribut ini hanya dapat digunakan dengan `Edm.String` bidang dan `Collection(Edm.String)` yang memiliki setidaknya salah satu yang dapat difilter, dapat diurutkan, atau dapat difaset ke true. Normalizer hanya dapat diatur pada bidang ketika ditambahkan ke indeks dan tidak dapat diubah nanti. Harus `null` untuk bidang kompleks. Nilai yang valid untuk normalizer yang telah ditentukan sebelumnya meliputi: `standard`- Huruf kecil teks diikuti dengan asciifolding. `lowercase`- Mengubah karakter menjadi huruf kecil. `uppercase` - Mengubah karakter menjadi huruf besar. `asciifolding` - Mengubah karakter yang tidak ada di blok Unicode Latin Dasar ke setara ASCII mereka, jika ada. Misalnya, mengubah à menjadi a. `elision`- Menghapus elisi dari awal token.
synonymMaps	Daftar nama peta sinonim untuk dikaitkan dengan bidang ini. Atribut ini hanya dapat digunakan dengan bidang yang dapat dicari. Saat ini hanya satu peta sinonim per bidang yang didukung. Menetapkan peta sinonim ke bidang memastikan bahwa istilah kueri yang menargetkan bidang tersebut diperluas pada waktu kueri menggunakan aturan di peta sinonim. Atribut ini dapat diubah pada bidang yang ada. Harus berupa `null` atau koleksi kosong untuk bidang kompleks.
fields	Daftar sub-bidang jika ini adalah bidang jenis `Edm.ComplexType` atau `Collection(Edm.ComplexType)`. Harus `null` atau kosong untuk bidang sederhana. Lihat Cara memodelkan jenis data kompleks di Azure Cognitive Search untuk informasi selengkapnya tentang cara dan kapan menggunakan sub-bidang.

Catatan

Bidang jenis Edm.String yang dapat difilter, dapat diurutkan, atau dapat difaset dapat memiliki panjang paling banyak 32 kilobyte. Ini karena nilai bidang tersebut diperlakukan sebagai istilah pencarian tunggal, dan panjang maksimum istilah dalam Azure Cognitive Search adalah 32 kilobyte. Jika Anda perlu menyimpan lebih banyak teks daripada ini dalam satu bidang string, Anda harus secara eksplisit mengatur dapat difilter, dapat diurutkan, dan dapat difaset ke false dalam definisi indeks Anda.

Mengatur bidang sebagai dapat dicari, dapat difilter, diurutkan, atau dapat difaset berdampak pada ukuran indeks dan performa kueri. Jangan atur atribut tersebut pada bidang yang tidak dimaksudkan untuk direferensikan dalam ekspresi kueri.

Jika bidang tidak diatur agar dapat dicari, dapat difilter, dapat diurutkan, atau dapat difaset, bidang tidak dapat direferensikan dalam ekspresi kueri apa pun. Ini berguna untuk bidang yang tidak digunakan dalam kueri, tetapi diperlukan dalam hasil pencarian.

normalizer

Menentukan normalizer kustom yang memiliki kombinasi filter karakter dan filter token yang ditentukan pengguna. Setelah menentukan normalizer kustom dalam indeks, Anda dapat menentukannya berdasarkan nama pada definisi bidang.

Atribut	Deskripsi
nama	Wajib diisi. Bidang string yang menentukan normalizer kustom yang ditentukan pengguna.
charFilters	Digunakan dalam normalizer kustom. Ini bisa menjadi satu atau beberapa filter karakter yang tersedia yang didukung untuk digunakan dalam normalizer kustom: pemetaan pattern_replace
tokenFilters	Digunakan dalam normalizer kustom. Ini bisa menjadi satu atau beberapa tilter token yang tersedia yang didukung untuk digunakan dalam normalizer kustom: arabic_normalization elisi cjk_width asciifolding german_normalization hindi_normalization indic_normalization persian_normalization scandinavian_normalization scandinavian_folding sorani_normalization huruf kecil huruf besar

Semantik

Konfigurasi semantik adalah bagian dari definisi indeks yang digunakan untuk mengonfigurasi bidang mana yang akan digunakan oleh pencarian semantik untuk peringkat, keterangan, sorotan, dan jawaban. Konfigurasi semantik terdiri dari bidang judul, bidang konten yang diprioritaskan, dan bidang kata kunci yang diprioritaskan. Setidaknya satu bidang perlu ditentukan antara ketiga sub-properti (titleField, prioritizedKeywordsFields dan prioritizedContentFields). Bidang jenis Edm.String apa pun atau Collection(Edm.String) dapat digunakan sebagai bagian dari konfigurasi semantik.

Untuk menggunakan pencarian semantik, Anda harus menentukan nama konfigurasi semantik pada waktu kueri. Untuk informasi selengkapnya, lihat Membuat kueri semantik.

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "name of the semantic configuration",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "..."
               },
           "prioritizedContentFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ]
         }
       }
     ]
   }
}

Atribut	Deskripsi
nama	Wajib diisi. Nama konfigurasi semantik.
prioritizedFields	Wajib diisi. Menjelaskan bidang judul, konten, dan kata kunci yang akan digunakan untuk peringkat, keterangan, sorotan, dan jawaban semantik. Setidaknya salah satu dari tiga sub-properti (titleField, prioritizedKeywordsFields dan prioritizedContentFields) perlu diatur.
prioritizedFields.titleField	Menentukan bidang judul yang akan digunakan untuk peringkat, keterangan, sorotan, dan jawaban semantik. Jika Anda tidak memiliki bidang judul di indeks Anda, biarkan bidang ini kosong.
prioritizedFields.prioritizedContentFields	Menentukan bidang konten yang akan digunakan untuk peringkat, keterangan, sorotan, dan jawaban semantik. Untuk hasil terbaik, bidang yang dipilih harus berisi teks dalam bentuk bahasa alami. Urutan bidang dalam array mewakili prioritasnya. Bidang dengan prioritas lebih rendah mungkin terpotong jika kontennya panjang.
prioritizedFields.prioritizedKeywordsFields	Menentukan bidang kata kunci yang akan digunakan untuk peringkat, keterangan, sorotan, dan jawaban semantik. Untuk hasil terbaik, bidang yang dipilih harus berisi daftar kata kunci. Urutan bidang dalam array mewakili prioritasnya. Bidang dengan prioritas lebih rendah mungkin terpotong jika kontennya panjang.

pemberi saran

Menentukan konstruksi yang menyimpan awalan untuk pencocokan pada kueri parsial seperti lengkapi otomatis dan saran.

Atribut	Deskripsi
nama	Wajib diisi. Nama pemberi saran.
sourceFields	Wajib diisi. Satu atau beberapa bidang string tempat Anda mengaktifkan pelengkapan otomatis atau hasil yang disarankan.
searchMode	Diperlukan, dan selalu atur ke `analyzingInfixMatching`. Ini menentukan bahwa pencocokan akan terjadi pada istilah apa pun dalam string kueri.