Dokumen Pencarian (Azure AI Search REST API)

Artikel
11/13/2023

Permintaan kueri menargetkan kumpulan dokumen dari satu indeks pada layanan pencarian. Ini termasuk parameter yang menentukan kriteria kecocokan, dan parameter yang membentuk respons. Mulai versi API Pratinjau 30-04-2021, Anda juga dapat menggunakan alias indeks untuk menargetkan indeks tertentu alih-alih menggunakan nama indeks itu sendiri.

Anda dapat menggunakan GET atau POST. Parameter kueri ditentukan pada string kueri untuk permintaan GET, dan di isi permintaan untuk permintaan POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Jika Anda menggunakan POST, tambahkan tindakan "pencarian" sebagai parameter URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Ketika dipanggil dengan GET, panjang URL permintaan tidak boleh melebihi 8 KB. Panjang ini biasanya cukup untuk sebagian besar aplikasi. Namun, beberapa aplikasi menghasilkan kueri besar, khususnya ketika ekspresi filter OData digunakan. Untuk aplikasi ini, HTTP POST adalah pilihan yang lebih baik karena memungkinkan filter yang lebih besar daripada GET.

Dengan POST, jumlah klausul dalam filter adalah faktor pembatas, bukan ukuran string filter mentah karena batas ukuran permintaan untuk POST adalah sekitar 16 MB. Meskipun batas ukuran permintaan POST besar, ekspresi filter tidak bisa sangat kompleks. Untuk informasi selengkapnya tentang batasan kompleksitas filter, lihat Sintaks Ekspresi OData untuk Pencarian Azure AI.

Parameter URI

Parameter	Deskripsi
[nama layanan]	Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
[nama indeks]/dokumen	Wajib diisi. Menentukan kumpulan dokumen dari indeks bernama.
[parameter kueri]	Parameter kueri ditentukan pada URI untuk permintaan GET dan di isi permintaan untuk permintaan POST.
versi-api	Wajib diisi. Versi stabil saat ini adalah `api-version=2020-06-30`. Lihat Versi API untuk versi lainnya. Untuk kueri, versi api selalu ditentukan sebagai parameter URI untuk GET dan POST.

Rekomendasi pengodean URL

Ingatlah untuk mengodekan URL parameter kueri tertentu saat memanggil GET REST API secara langsung. Untuk operasi Dokumen Pencarian , pengodean URL mungkin diperlukan untuk parameter kueri berikut:

pencarian
$filter
Faset
highlightPreTag
highlightPostTag

Pengodean URL hanya direkomendasikan untuk parameter individual. Jika Anda secara tidak sengaja mengodekan URL seluruh string kueri (semuanya setelah ?), permintaan akan rusak.

Selain itu, pengodean URL hanya diperlukan saat memanggil REST API secara langsung menggunakan GET. Tidak ada pengodean URL yang diperlukan saat menggunakan POST, atau saat menggunakan pustaka klien Azure AI Search .NET, yang menangani pengodean untuk Anda.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang	Deskripsi
Jenis-Konten	Wajib diisi. Atur 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. Permintaan kueri terhadap koleksi dokumen dapat menentukan kunci admin atau kunci kueri sebagai kunci API. Kunci kueri digunakan untuk operasi baca-saja terhadap kumpulan dokumen. Lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci untuk detailnya.

Bidang

Deskripsi

Jenis-Konten

Wajib diisi. Atur 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. Permintaan kueri terhadap koleksi dokumen dapat menentukan kunci admin atau kunci kueri sebagai kunci API. Kunci kueri digunakan untuk operasi baca-saja terhadap kumpulan dokumen. Lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci untuk detailnya.

Isi Permintaan

Untuk GET: None.

Untuk POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Kelanjutan Respons Pencarian Parsial

Terkadang Pencarian Azure AI tidak dapat mengembalikan semua hasil yang diminta dalam satu respons Pencarian. Ini dapat terjadi karena alasan yang berbeda, seperti ketika kueri meminta terlalu banyak dokumen dengan tidak menentukan $top atau menentukan nilai untuk $top yang terlalu besar. Dalam kasus seperti itu, Azure AI Search menyertakan @odata.nextLink anotasi dalam isi respons, dan juga @search.nextPageParameters jika itu adalah permintaan POST. Anda dapat menggunakan nilai anotasi ini untuk merumuskan permintaan Pencarian lain untuk mendapatkan bagian berikutnya dari respons pencarian. Ini disebut kelanjutan dari permintaan Pencarian asli, dan anotasi umumnya disebut token kelanjutan. Lihat contoh dalam Respons di bawah ini untuk detail tentang sintaks anotasi ini dan tempat anotasi tersebut muncul di isi respons.

Alasan mengapa Azure AI Search mungkin mengembalikan token kelanjutan khusus implementasi dan dapat berubah. Klien yang kuat harus selalu siap untuk menangani kasus di mana lebih sedikit dokumen dari yang diharapkan dikembalikan dan token kelanjutan disertakan untuk terus mengambil dokumen. Perhatikan juga bahwa Anda harus menggunakan metode HTTP yang sama dengan permintaan asli untuk melanjutkan. Misalnya, jika Anda mengirim permintaan GET, permintaan kelanjutan apa pun yang Anda kirim juga harus menggunakan GET (dan juga untuk POST).

Catatan

Tujuan dan @odata.nextLink@search.nextPageParameters adalah untuk melindungi layanan dari kueri yang meminta terlalu banyak hasil, bukan untuk menyediakan mekanisme umum untuk penomoran. Jika Anda ingin menelusuri hasil, gunakan $top dan $skip bersama-sama. Misalnya, jika Anda ingin halaman berukuran 10, permintaan pertama Anda harus memiliki $top=10 dan $skip=0, permintaan kedua harus memiliki $top=10 dan $skip=10, permintaan ketiga harus memiliki $top=10 dan $skip=20, dan sebagainya.

Parameter Kueri

Kueri menerima beberapa parameter pada URL saat dipanggil dengan GET, dan sebagai properti JSON di isi permintaan saat dipanggil dengan POST. Sintaks untuk beberapa parameter sedikit berbeda antara GET dan POST. Perbedaan ini dicatat sebagaimana berlaku di bawah ini.

Nama	Jenis	Deskripsi
versi-api	string	Wajib diisi. Versi REST API yang digunakan untuk permintaan tersebut. Untuk daftar versi yang didukung, lihat versi API. Untuk operasi ini, versi api ditentukan sebagai parameter URI terlepas dari apakah Anda memanggil Dokumen Pencarian dengan GET atau POST.
`$count`	boolean	Opsional. Nilai yang valid adalah "true" atau "false". Default ke "false". Ketika dipanggil dengan POST, parameter ini diberi nama hitungan alih-alih `$count`. Menentukan apakah akan mengambil jumlah total hasil. Ini adalah jumlah semua dokumen yang cocok dengan parameter pencarian dan $filter, mengabaikan `$top` dan `$skip`. Mengatur nilai ini ke "true" dapat menurunkan performa. Hitungan akurat jika indeks stabil, tetapi akan di bawah atau melaporkan dokumen apa pun yang secara aktif ditambahkan, diperbarui, atau dihapus. Jika Anda hanya ingin mendapatkan hitungan tanpa dokumen apa pun, Anda dapat menggunakan `$top`=0.
faset atau faset	string	Opsional. Bidang yang akan difasetkan oleh, di mana bidang dikaitkan sebagai "dapat difaset". Ketika dipanggil dengan GET, `facet` adalah bidang (`facet: field1`). Ketika dipanggil dengan POST, parameter ini dinamai `facets` alih-alih `facet` dan ditentukan sebagai array (`facets: [field1, field2, field3]`). String mungkin berisi parameter untuk menyesuaikan faset, yang dinyatakan sebagai pasangan nilai nama yang dipisahkan koma. Parameter yang valid adalah "count", "sort", "values", "interval", dan "timeoffset". "count" adalah jumlah maksimum istilah faset; defaultnya adalah 10. Tidak ada batas atas jumlah istilah, tetapi nilai yang lebih tinggi menurunkan performa, terutama jika bidang tersaring berisi sejumlah besar istilah unik. Misalnya, "facet=category,count:5" mendapatkan lima kategori teratas dalam hasil faset. Jika parameter hitungan kurang dari jumlah istilah unik, hasilnya mungkin tidak akurat. Hal ini disebabkan oleh cara kueri faset didistribusikan di seluruh pecahan. Anda dapat mengatur hitungan ke nol atau ke nilai yang lebih besar dari atau sama dengan jumlah nilai unik di bidang yang dapat difaset untuk mendapatkan jumlah yang akurat di semua pecahan. Tradeoff adalah latensi yang ditingkatkan. "sort" dapat diatur ke "count", "-count", "value", "-value". Gunakan hitungan untuk mengurutkan turun menurut hitungan. Gunakan -count untuk mengurutkan naik menurut hitungan. Gunakan nilai untuk mengurutkan naik menurut nilai. Gunakan -value untuk mengurutkan turun menurut nilai (misalnya, "facet=category,count:3,sort:count" mendapatkan tiga kategori teratas dalam hasil faset dalam urutan menurung berdasarkan jumlah dokumen dengan setiap nama kota). Jika tiga kategori teratas adalah Budget, Motel, dan Luxury, dan Budget memiliki 5 hit, Motel memiliki 6, dan Luxury memiliki 4, maka ember berada dalam pesanan Motel, Budget, Luxury. Untuk -value, "facet=rating,sort:-value" menghasilkan bucket untuk semua peringkat yang mungkin, dalam urutan menurung berdasarkan nilai (misalnya, jika peringkat dari 1 hingga 5, bucket diurutkan 5, 4, 3, 2, 1, terlepas dari berapa banyak dokumen yang cocok dengan setiap peringkat). "nilai" dapat diatur ke nilai numerik yang dibatasi pipa atau Edm.DateTimeOffset yang menentukan sekumpulan dinamis nilai entri faset (misalnya, "facet=baseRate,values:10 \| 20" menghasilkan tiga wadah: satu untuk tarif dasar 0 hingga tetapi tidak termasuk 10, satu untuk 10 hingga tetapi tidak termasuk 20, dan satu untuk 20 dan lebih tinggi). String "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" menghasilkan dua wadah: satu untuk hotel yang direnovasi sebelum Februari 2010, dan satu untuk hotel yang direnovasi 1 Februari 2010 atau yang lebih baru. Nilai harus dicantumkan secara berurutan, urutan naik untuk mendapatkan hasil yang diharapkan. "interval" adalah interval bilangan bulat yang lebih besar dari 0 untuk angka, atau menit, jam, hari, minggu, bulan, kuartal, tahun untuk nilai waktu tanggal. Misalnya, "facet=baseRate,interval:100" menghasilkan wadah berdasarkan rentang laju dasar ukuran 100. Jika tarif dasar semuanya antara $60 dan $600, akan ada wadah untuk 0-100, 100-200, 200-300, 300-400, 400-500, dan 500-600. String "facet=lastRenovationDate,interval:year" menghasilkan satu wadah untuk setiap tahun ketika hotel direnovasi. "timeoffset" dapat diatur ke ([+-]hh:mm, [+-]hhmm, atau [+-]hh). Jika digunakan, parameter timeoffset harus dikombinasikan dengan opsi interval, dan hanya saat diterapkan ke bidang jenis Edm.DateTimeOffset. Nilai menentukan offset waktu UTC untuk memperkirakan dalam mengatur batas waktu. Misalnya: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" menggunakan batas hari yang dimulai pada 01:00:00 UTC (tengah malam di zona waktu target). hitung dan urutkan dapat digabungkan dalam spesifikasi faset yang sama, tetapi tidak dapat dikombinasikan dengan interval atau nilai, dan interval dan nilai tidak dapat digabungkan bersama-sama. Faset interval pada waktu tanggal dihitung berdasarkan waktu UTC jika timeoffset tidak ditentukan. Misalnya: untuk "facet=lastRenovationDate,interval:day", batas hari dimulai pada 00:00:00 UTC.
$filter	string	Opsional. Ekspresi pencarian terstruktur dalam sintaks OData standar. Hanya bidang yang dapat difilter yang dapat digunakan dalam filter. Saat memanggil dengan POST, parameter ini diberi nama filter alih-alih $filter. Lihat Sintaks Ekspresi OData untuk Pencarian Azure AI untuk detail tentang subset tata bahasa ekspresi OData yang didukung Azure AI Search.
Menyoroti	string	Opsional. Sekumpulan nama bidang yang dipisahkan koma yang digunakan untuk sorotan temuan. Hanya bidang yang dapat dicari yang dapat digunakan untuk penyorotan klik. Secara default, Azure AI Search mengembalikan hingga 5 sorotan per bidang. Batas dapat dikonfigurasi per bidang dengan menambahkan "-<max # of highlights>" mengikuti nama bidang. Misalnya, "highlight=title-3,description-10" mengembalikan hingga 3 temuan yang disorot dari bidang judul dan hingga 10 temuan dari bidang deskripsi. Jumlah maksimum sorotan harus berupa bilangan bulat antara 1 dan 1000 inklusif.
highlightPostTag	string	Opsional. Default ke `"</em>"`. Tag string yang ditambahkan ke istilah yang disorot.. Harus diatur dengan highlightPreTag. Karakter yang dicadangkan dalam URL harus dikodekan persen (misalnya, %23, bukan #).
highlightPreTag	string	Opsional. Default ke `"</em>"`. Tag string yang ditambahkan ke istilah yang disorot. Harus diatur dengan highlightPostTag. Karakter yang dicadangkan dalam URL harus dikodekan persen (misalnya, %23, bukan #).
minimumCoverage	bilangan bulat	Opsional. Nilai yang valid adalah angka antara 0 dan 100, menunjukkan persentase indeks yang harus tersedia untuk melayani kueri sebelum dapat dilaporkan sebagai keberhasilan. Default ke "100". Cakupan seratus persen berarti bahwa semua pecahan menanggapi permintaan (baik masalah kesehatan layanan maupun aktivitas pemeliharaan mengurangi cakupan). Di bawah pengaturan default, cakupan kurang dari penuh mengembalikan kode status HTTP 503. Menurunkan minimumCoverage dapat berguna jika terjadi kesalahan 503 dan Anda ingin meningkatkan probabilitas keberhasilan kueri, terutama untuk layanan yang dikonfigurasi untuk satu replika. Jika Anda mengatur minimumCoverage dan Pencarian berhasil, itu mengembalikan HTTP 200 dan menyertakan @search.coverage nilai dalam respons yang menunjukkan persentase indeks yang disertakan dalam kueri. Dalam skenario ini, tidak semua dokumen yang cocok dijamin akan ada dalam hasil pencarian, tetapi jika ketersediaan pencarian lebih penting daripada pengenalan, maka mengurangi cakupan dapat menjadi strategi mitigasi yang layak.
$orderby	string	Opsional. Daftar ekspresi yang dipisahkan koma untuk mengurutkan hasilnya. Ketika dipanggil dengan POST, parameter ini dinamai orderby alih-alih $orderby. Setiap ekspresi dapat berupa nama bidang atau panggilan ke fungsi geo.distance(). Setiap ekspresi dapat diikuti dengan "asc" untuk menunjukkan naik, dan "turun" untuk menunjukkan turun. Jika ada nilai null dalam bidang sortir, null muncul terlebih dahulu dalam urutan naik dan terakhir dalam urutan menurun. Defaultnya adalah urutan naik. Ikatan akan dipecah oleh skor kecocokan dokumen. Jika tidak ada $orderby yang ditentukan, urutan pengurutan default turun menurut skor kecocokan dokumen. Ada batas 32 klausa untuk $orderby.
queryType	string	Opsional. Nilai yang valid adalah "sederhana" atau "penuh". Default ke "sederhana". "sederhana" menginterpretasikan string kueri menggunakan sintaks kueri sederhana yang memungkinkan simbol seperti `+`, `*` dan `""`. Kueri dievaluasi di semua bidang yang dapat dicari (atau bidang yang ditunjukkan di searchFields) di setiap dokumen secara default. "penuh" menginterpretasikan string kueri menggunakan sintaks kueri Lucene lengkap yang memungkinkan pencarian khusus bidang dan tertimbang. Pencarian rentang dalam bahasa kueri Lucene tidak didukung demi $filter, yang menawarkan fungsionalitas serupa.
scoringParameter	string	Opsional. Menunjukkan nilai untuk setiap parameter yang ditentukan dalam fungsi penilaian (seperti referencePointParameter) menggunakan format "name-value1,value2,..." Ketika dipanggil dengan POST, parameter ini diberi nama scoringParameters alih-alih scoringParameter. Selain itu, Anda menentukannya sebagai array string JSON di mana setiap string adalah pasangan nilai nama terpisah. Untuk profil penilaian yang menyertakan fungsi, pisahkan fungsi dari daftar inputnya dengan `-` karakter. Misalnya, fungsi yang disebut `"mylocation"` adalah "&scoringParameter=mylocation--122.2,44.8". Garis putus pertama memisahkan nama fungsi dari daftar nilai, sementara garis putus-putus kedua adalah bagian dari nilai pertama (garis bujur dalam contoh ini). Untuk parameter penilaian seperti untuk peningkatan tag yang dapat berisi koma, Anda dapat menghindari nilai tersebut dalam daftar menggunakan tanda kutip tunggal. Jika nilai itu sendiri berisi tanda kutip tunggal, Anda dapat menghindarinya dengan menggandakannya. Misalkan Anda memiliki parameter peningkatan tag yang disebut `"mytag"` dan Anda ingin meningkatkan nilai tag "Hello, O'Brien" dan "Smith", opsi string kueri kemudian akan menjadi "&scoringParameter=mytag-'Hello, O''Brien',Smith". Kuotasi hanya diperlukan untuk nilai yang berisi koma.
scoringProfile	string	Opsional. Nama profil penilaian untuk mengevaluasi skor kecocokan untuk dokumen yang cocok untuk mengurutkan hasil.
scoringStatistics	string	Opsional. Nilai yang valid adalah "lokal" atau "global". Default ke "lokal". Tentukan apakah akan menghitung statistik penilaian, seperti frekuensi dokumen, secara global (di semua pecahan) untuk penilaian yang lebih konsisten, atau secara lokal (pada pecahan saat ini) untuk latensi yang lebih rendah. Lihat Statistik Penilaian di Pencarian Azure AI. Statistik penilaian akan selalu dihitung secara lokal untuk istilah yang menggunakan pencarian fuzzy ('~').
pencarian	string	Opsional. Teks yang akan dicari. Semua bidang yang dapat dicari dicari secara default kecuali searchFields ditentukan. Dalam indeks, teks dalam bidang yang dapat dicari diberi token, sehingga beberapa istilah dapat dipisahkan oleh spasi kosong (misalnya: 'search=hello world'). Untuk mencocokkan istilah apa pun, gunakan `` (ini dapat berguna untuk kueri filter boolean). Menghilangkan parameter ini memiliki efek yang sama dengan mengaturnya ke ``. Lihat Sintaks kueri sederhana untuk spesifik pada sintaks pencarian. Hasil terkadang bisa mengejutkan saat mengkueri bidang yang dapat dicari. Tokenizer mencakup logika untuk menangani kasus yang umum untuk teks bahasa Inggris seperti apostrof, koma dalam angka, dan sebagainya. Misalnya, 'search=123,456' akan cocok dengan satu istilah '123,456' daripada istilah individu '123' dan '456', karena koma digunakan sebagai pemisah ribuan untuk angka besar dalam bahasa Inggris. Untuk alasan ini, sebaiknya gunakan spasi kosong daripada tanda baca untuk memisahkan istilah dalam parameter pencarian.
searchMode	string	Opsional. Nilai yang valid adalah Default "any" atau "all" ke "any". Menentukan apakah salah satu atau semua istilah pencarian harus dicocokkan untuk menghitung dokumen sebagai kecocokan.
searchFields	string	Opsional. Daftar nama bidang yang dipisahkan koma untuk mencari teks yang ditentukan. Bidang target harus ditandai sebagai dapat dicari dalam skema indeks.
$select	string	Opsional. Daftar bidang yang dipisahkan koma untuk disertakan dalam tataan hasil. Hanya bidang yang ditandai sebagai dapat diambil yang dapat disertakan dalam klausa ini. Jika tidak ditentukan atau diatur ke `*`, semua bidang yang ditandai sebagai dapat diambil dalam skema disertakan dalam proyeksi. Ketika dipanggil dengan POST, parameter ini diberi nama pilih alih-alih $select.
sessionId	string	Opsional. Menggunakan sessionId membantu meningkatkan konsistensi skor relevansi untuk layanan pencarian dengan beberapa replika. Dalam konfigurasi multi-replika, mungkin ada sedikit perbedaan antara skor relevansi masing-masing dokumen untuk kueri yang sama. Ketika ID sesi disediakan, layanan melakukan upaya terbaik untuk merutekan permintaan tertentu ke replika yang sama untuk sesi tersebut. Waspadalah bahwa menggunakan kembali nilai ID sesi yang sama berulang kali dapat mengganggu penyeimbangan beban permintaan di seluruh replika dan berdampak buruk pada performa layanan pencarian. Nilai yang digunakan sebagai sessionId tidak dapat dimulai dengan karakter '_'. Jika layanan tidak memiliki replika apa pun, parameter ini tidak berpengaruh pada performa atau konsistensi skor.
$skip	bilangan bulat	Opsional. Jumlah hasil pencarian yang akan dilewati. Ketika dipanggil dengan POST, parameter ini diberi nama lewati alih-alih `$skip`. Nilai ini tidak boleh lebih besar dari 100.000. Jika Anda perlu memindai dokumen secara berurutan, tetapi tidak dapat menggunakan `$skip` karena batasan ini, pertimbangkan untuk menggunakan $orderby pada bidang yang memiliki nilai unik untuk setiap dokumen dalam indeks (seperti kunci dokumen, misalnya) dan $filter dengan kueri rentang sebagai gantinya.
$top	bilangan bulat	Pilihan. Jumlah hasil pencarian yang akan diambil. Ini default ke 50. Ketika dipanggil dengan POST, parameter ini dinamai teratas alih-alih `$top`. Jika Anda menentukan nilai yang lebih besar dari 1000 dan ada lebih dari 1000 hasil, hanya 1000 hasil pertama yang akan dikembalikan, bersama dengan tautan ke halaman hasil berikutnya (lihat @odata.nextLink pada contoh di bawah). Azure AI Search menggunakan penomoran sisi server untuk mencegah kueri mengambil terlalu banyak dokumen sekaligus. Ukuran halaman default adalah 50, sedangkan ukuran halaman maksimum adalah 1000. Ini berarti bahwa secara default Dokumen Pencarian mengembalikan paling banyak 50 hasil jika Anda tidak menentukan `$top`. Jika ada lebih dari 50 hasil, respons menyertakan informasi untuk mengambil halaman berikutnya dari paling banyak 50 hasil (lihat "@odata.nextLink" dan "@search.nextPageParameters" dalam Contoh di bawah ini. Demikian pula, jika Anda menentukan nilai yang lebih besar dari 1000 untuk `$top` dan ada lebih dari 1000 hasil, hanya 1000 hasil pertama yang dikembalikan, bersama dengan informasi untuk mengambil halaman berikutnya dari paling banyak 1000 hasil.

Respons

Kode Status: 200 OK dikembalikan untuk respons yang berhasil.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Contoh

Anda dapat menemukan contoh lainnya dalam Sintaks Ekspresi OData untuk Pencarian Azure AI.

Cari Indeks yang diurutkan menurun menurut tanggal:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Dalam pencarian tersaring, cari indeks dan ambil faset untuk kategori, peringkat, tag, dan item dengan baseRate dalam rentang tertentu.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
Perhatikan faset terakhir ada di subbidang. Faset menghitung dokumen induk (Hotel) dan bukan subdokumen menengah (Kamar), sehingga respons menentukan jumlah hotel yang memiliki kamar di setiap wadah harga.

Menggunakan filter, persempit hasil kueri tersaring sebelumnya setelah pengguna memilih Peringkat 3 dan kategori "Motel".

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Dalam pencarian tersaring, atur batas atas pada istilah unik yang dikembalikan dalam kueri. Defaultnya adalah 10, tetapi Anda dapat menambah atau mengurangi nilai ini menggunakan parameter hitungan pada atribut faset. Contoh ini mengembalikan faset untuk kota, dibatasi hingga 5.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Cari Indeks dalam bidang tertentu (misalnya, bidang bahasa):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Cari Indeks di beberapa bidang. Misalnya, Anda dapat menyimpan dan mengkueri bidang yang dapat dicari dalam beberapa bahasa, semuanya dalam indeks yang sama. Jika deskripsi bahasa Inggris dan Prancis berdampingan dalam dokumen yang sama, Anda bisa mengembalikan salah satu atau semua dalam hasil kueri:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Anda hanya bisa mengkueri indeks pada satu waktu. Jangan membuat beberapa indeks untuk setiap bahasa kecuali Anda berencana untuk mengkueri satu per satu.

Halaman - Dapatkan halaman pertama item (ukuran halaman adalah 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Halaman - Dapatkan halaman kedua item (ukuran halaman adalah 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Ambil sekumpulan bidang tertentu:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Ambil dokumen yang cocok dengan ekspresi filter tertentu:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Cari indeks dan kembalikan fragmen dengan sorotan temuan:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Cari indeks dan kembalikan dokumen yang diurutkan dari lebih dekat ke lebih jauh dari lokasi referensi:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Cari indeks dengan asumsi ada profil penilaian yang disebut "geo" dengan dua fungsi penilaian jarak, satu mendefinisikan parameter yang disebut "currentLocation" dan satu mendefinisikan parameter yang disebut "lastLocation". Dalam contoh berikut, "currentLocation" memiliki pemisah satu tanda hubung (-). Ini diikuti oleh koordinat bujur dan lintang, di mana bujur adalah nilai negatif.

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

Temukan dokumen dalam indeks menggunakan sintaks kueri sederhana. Kueri ini mengembalikan hotel di mana bidang yang dapat dicari berisi istilah "kenyamanan" dan "lokasi" tetapi bukan "motel":
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Tip

Penggunaan searchMode=all mengambil alih default searchMode=any, memastikan itu -motel berarti "AND NOT" alih-alih "OR NOT". Tanpa searchMode=all, Anda mendapatkan "ATAU TIDAK" yang berkembang daripada membatasi hasil pencarian, dan ini bisa berlawanan intuitif bagi beberapa pengguna.
Temukan dokumen dalam indeks menggunakan sintaks kueri Lucene). Kueri ini mengembalikan hotel di mana bidang kategori berisi istilah "anggaran" dan semua bidang yang dapat dicari yang berisi frasa "baru-baru ini direnovasi". Dokumen yang berisi frasa "baru saja direnovasi" diberi peringkat lebih tinggi sebagai hasil dari nilai peningkatan istilah (3)
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
Temukan dokumen dalam indeks sambil mendukung penilaian yang konsisten atas latensi yang lebih rendah. Kueri ini menghitung frekuensi dokumen di seluruh indeks, dan melakukan upaya terbaik untuk menargetkan replika yang sama untuk semua kueri dalam "sesi" yang sama, yang membantu menghasilkan peringkat yang stabil dan dapat direproduksi.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```