Documents - Suggest Post

Layanan:: Search Service

Versi API:: 2026-08-01-preview

Menyarankan dokumen dalam indeks yang cocok dengan teks kueri parsial yang diberikan.

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2026-08-01-preview

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
endpoint	path	True	string (uri)	URL titik akhir layanan pencarian.
indexName	path	True	string	Nama indeks.
api-version	query	True	string minLength: 1	Versi API yang akan digunakan untuk operasi ini.

Header Permintaan

Nama	Diperlukan	Jenis	Deskripsi
Accept		Accept	Header Terima.
x-ms-client-request-id		string (uuid)	Pengidentifikasi string yang buram dan unik secara global yang dihasilkan klien untuk permintaan tersebut.

Isi Permintaan

Nama	Diperlukan	Jenis	Deskripsi
search	True	string	Teks pencarian yang digunakan untuk menyarankan dokumen. Harus minimal 1 karakter, dan tidak lebih dari 100 karakter.
suggesterName	True	string	Nama pemberi saran seperti yang ditentukan dalam koleksi pemberi saran yang menjadi bagian dari definisi indeks.
filter		string	Ekspresi OData yang memfilter dokumen yang dipertimbangkan untuk saran.
fuzzy		boolean	Nilai yang menunjukkan apakah akan menggunakan pencocokan fuzzy untuk kueri saran. Secara default adalah false. Jika diatur ke true, kueri akan menemukan saran meskipun ada karakter yang diganti atau hilang dalam teks pencarian. Meskipun ini memberikan pengalaman yang lebih baik dalam beberapa skenario, ini datang dengan biaya kinerja karena pencarian saran kabur lebih lambat dan menghabiskan lebih banyak sumber daya.
highlightPostTag		string	Tag string yang ditambahkan untuk menekan sorotan. Harus diatur dengan highlightPreTag. Jika dihilangkan, tekan penyorotan saran dinonaktifkan.
highlightPreTag		string	Tag string yang sebelumnya ditangguhkan untuk menekan sorotan. Harus diatur dengan highlightPostTag. Jika dihilangkan, tekan penyorotan saran dinonaktifkan.
minimumCoverage		number (double)	Angka antara 0 dan 100 yang menunjukkan persentase indeks yang harus dicakup oleh kueri saran agar kueri dilaporkan sebagai keberhasilan. Parameter ini dapat berguna untuk memastikan ketersediaan pencarian bahkan untuk layanan hanya dengan satu replika. Defaultnya adalah 80.
orderby		string	Daftar ekspresi OData $orderby yang dipisahkan koma untuk mengurutkan hasilnya. Setiap ekspresi dapat berupa nama bidang atau panggilan ke fungsi geo.distance() atau search.score(). Setiap ekspresi dapat diikuti oleh asc untuk menunjukkan naik, atau turun untuk menunjukkan 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. Paling banyak ada 32 klausa $orderby.
searchFields		string	Daftar nama bidang yang dipisahkan koma untuk mencari teks pencarian yang ditentukan. Bidang target harus disertakan dalam saran yang ditentukan.
select		string	Daftar bidang yang dipisahkan koma untuk diambil. Jika tidak ditentukan, hanya bidang kunci yang akan disertakan dalam hasil.
top		integer (int32)	Jumlah saran yang akan diambil. Ini harus berupa nilai antara 1 dan 100. Pengaturan awal adalah 5.

Respons

Nama	Jenis	Deskripsi
200 OK	SuggestDocumentsResult	Permintaan telah berhasil.
Other Status Codes	ErrorResponse	Respons kesalahan yang tidak terduga.

Keamanan

api-key

Jenis: apiKey
Dalam: header

OAuth2Auth

Jenis: oauth2
Alur: implicit
URL Otorisasi: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Cakupan

Nama	Deskripsi
https://search.azure.com/.default

Contoh

SearchIndexSuggestDocumentsPost

Permintaan sampel

HTTP

POST https://typespecpreviewexampleservice.search.windows.net/indexes('preview-test')/docs/search.post.suggest?api-version=2026-08-01-preview



{
  "search": "p",
  "suggesterName": "sg",
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "top": 10
}

Respon sampel

Kode status:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

Definisi

Nama	Deskripsi
Accept	Header Terima.
ErrorAdditionalInfo	Informasi tambahan tentang kesalahan pengelolaan sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Respons kesalahan umum untuk semua API Azure Resource Manager untuk mengembalikan detail kesalahan untuk operasi yang gagal. (Ini juga mengikuti format respons kesalahan OData.).
SuggestDocumentsResult	Respons yang berisi hasil kueri saran dari indeks.
SuggestRequest	Parameter untuk pemfilteran, pengurutan, pencocokan fuzzy, dan perilaku kueri saran lainnya.
SuggestResult	Hasil yang berisi dokumen yang ditemukan oleh kueri saran, ditambah metadata terkait.

Accept

Enumerasi

Header Terima.

Nilai	Deskripsi
application/json;odata.metadata=none

ErrorAdditionalInfo

Objek

Informasi tambahan tentang kesalahan pengelolaan sumber daya.

Nama	Jenis	Deskripsi
info		Info tambahan.
type	string	Jenis informasi tambahan.

ErrorDetail

Objek

Detail kesalahan.

Nama	Jenis	Deskripsi
additionalInfo	ErrorAdditionalInfo[]	Informasi tambahan tentang kesalahan.
code	string	Kode kesalahan.
details	ErrorDetail[]	Rincian kesalahan.
message	string	Pesan kesalahan.
target	string	Sasaran kesalahan.

ErrorResponse

Objek

Respons kesalahan umum untuk semua API Azure Resource Manager untuk mengembalikan detail kesalahan untuk operasi yang gagal. (Ini juga mengikuti format respons kesalahan OData.).

Nama	Jenis	Deskripsi
error	ErrorDetail	Objek kesalahan.

SuggestDocumentsResult

Objek

Respons yang berisi hasil kueri saran dari indeks.

Nama	Jenis	Deskripsi
@search.coverage	number (double)	Nilai yang menunjukkan persentase indeks yang disertakan dalam kueri, atau null jika minimumCoverage tidak diatur dalam permintaan.
value	SuggestResult[]	Urutan hasil yang dikembalikan oleh kueri.

SuggestRequest

Objek

Parameter untuk pemfilteran, pengurutan, pencocokan fuzzy, dan perilaku kueri saran lainnya.

Nama	Jenis	Deskripsi
filter	string	Ekspresi OData yang memfilter dokumen yang dipertimbangkan untuk saran.
fuzzy	boolean	Nilai yang menunjukkan apakah akan menggunakan pencocokan fuzzy untuk kueri saran. Secara default adalah false. Jika diatur ke true, kueri akan menemukan saran meskipun ada karakter yang diganti atau hilang dalam teks pencarian. Meskipun ini memberikan pengalaman yang lebih baik dalam beberapa skenario, ini datang dengan biaya kinerja karena pencarian saran kabur lebih lambat dan menghabiskan lebih banyak sumber daya.
highlightPostTag	string	Tag string yang ditambahkan untuk menekan sorotan. Harus diatur dengan highlightPreTag. Jika dihilangkan, tekan penyorotan saran dinonaktifkan.
highlightPreTag	string	Tag string yang sebelumnya ditangguhkan untuk menekan sorotan. Harus diatur dengan highlightPostTag. Jika dihilangkan, tekan penyorotan saran dinonaktifkan.
minimumCoverage	number (double)	Angka antara 0 dan 100 yang menunjukkan persentase indeks yang harus dicakup oleh kueri saran agar kueri dilaporkan sebagai keberhasilan. Parameter ini dapat berguna untuk memastikan ketersediaan pencarian bahkan untuk layanan hanya dengan satu replika. Defaultnya adalah 80.
orderby	string	Daftar ekspresi OData $orderby yang dipisahkan koma untuk mengurutkan hasilnya. Setiap ekspresi dapat berupa nama bidang atau panggilan ke fungsi geo.distance() atau search.score(). Setiap ekspresi dapat diikuti oleh asc untuk menunjukkan naik, atau turun untuk menunjukkan 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. Paling banyak ada 32 klausa $orderby.
search	string	Teks pencarian yang digunakan untuk menyarankan dokumen. Harus minimal 1 karakter, dan tidak lebih dari 100 karakter.
searchFields	string	Daftar nama bidang yang dipisahkan koma untuk mencari teks pencarian yang ditentukan. Bidang target harus disertakan dalam saran yang ditentukan.
select	string	Daftar bidang yang dipisahkan koma untuk diambil. Jika tidak ditentukan, hanya bidang kunci yang akan disertakan dalam hasil.
suggesterName	string	Nama pemberi saran seperti yang ditentukan dalam koleksi pemberi saran yang menjadi bagian dari definisi indeks.
top	integer (int32)	Jumlah saran yang akan diambil. Ini harus berupa nilai antara 1 dan 100. Pengaturan awal adalah 5.

SuggestResult

Objek

Hasil yang berisi dokumen yang ditemukan oleh kueri saran, ditambah metadata terkait.

Nama	Jenis	Deskripsi
@search.text	string	Teks hasil saran.