Documents - Suggest Get

服務:: Search Service

API 版本:: 2026-08-01-preview

建議索引中符合指定部分查詢文字的文件。

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

含選擇性參數:

GET {endpoint}/indexes('{indexName}')/docs/search.suggest?api-version=2026-08-01-preview&search={search}&suggesterName={suggesterName}&$filter={$filter}&fuzzy={fuzzy}&highlightPostTag={highlightPostTag}&highlightPreTag={highlightPreTag}&minimumCoverage={minimumCoverage}&$orderby={$orderby}&searchFields={searchFields}&$select={$select}&$top={$top}

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string (uri)	搜尋服務的端點 URL。
indexName	path	True	string	索引的名稱。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。
search	query	True	string	要用來建議檔的搜尋文字。必須至少有 1 個字元，且不超過 100 個字元。
suggesterName	query	True	string	建議工具的名稱，如建議工具集合中所指定，屬於索引定義的一部分。
$filter	query		string	一個 OData 運算式，可篩選考慮建議的文件。
$orderby	query		string[]	要排序結果的 OData $orderby表示式清單。每個運算式可以是功能變數名稱或對 geo.distance（）或 search.score（）函式的呼叫。每個表達式後面可以接著 asc 表示遞增，或 desc 表示遞減。預設值為遞增順序。系結會因檔比對分數而中斷。如果未指定任何$orderby，則預設排序順序會依檔比對分數遞減。最多可以有 32 個$orderby子句。
$select	query		string[]	要擷取的欄位清單。如果未指定，則只會在結果中包含索引鍵欄位。
$top	query		integer (int32)	要擷取的建議數目。值必須是介於 1 到 100 之間的數字。預設值為 5。
fuzzy	query		boolean	指出是否要針對建議查詢使用模糊比對的值。預設值為 false。當設定為 true 時，即使搜尋文字中有替換或遺漏的字元，查詢也會尋找字詞。雖然這在某些情況下提供了更好的體驗，但它會以效能成本為代價，因為模糊建議查詢速度較慢且耗用更多資源。
highlightPostTag	query		string	附加至叫用醒目提示的字串標記。必須使用 highlightPreTag 進行設定。如果省略，則會停用建議的點擊醒目提示。
highlightPreTag	query		string	在叫用醒目提示前面加上的字串標記。必須使用 highlightPostTag 進行設定。如果省略，則會停用建議的點擊醒目提示。
minimumCoverage	query		number (double)	介於 0 到 100 之間的數字，指出建議查詢必須涵蓋的索引百分比，才能將查詢報告為成功。此參數對於確保搜尋可用性，即使是只有一個複本的服務，也很有用。預設值為 80。
searchFields	query		string[]	要搜尋指定搜尋文字的欄位名稱清單。目標欄位必須包含在指定的建議器中。

要求標頭

名稱	必要	類型	Description
Accept		Accept	接受標頭。
x-ms-client-request-id		string (uuid)	要求不透明、全域唯一、用戶端產生的字串標識碼。

回應

名稱	類型	Description
200 OK	SuggestDocumentsResult	要求已成功。
Other Status Codes	ErrorResponse	未預期的錯誤回應。

安全性

api-key

類型: apiKey
位於: header

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

範圍

名稱	Description
https://search.azure.com/.default

範例

SearchIndexSuggestDocumentsGet

範例要求

HTTP

GET https://myservice.search.windows.net/indexes('myindex')/docs/search.suggest?api-version=2026-08-01-preview&search=hote&suggesterName=sg&$filter=rating gt 10&fuzzy=False&highlightPostTag=</em>&highlightPreTag=<em>&minimumCoverage=80&$orderby=search.score() desc,rating desc&searchFields=title&$select=docId,title,description&$top=10

範例回覆

狀態碼:: 200

{
  "value": [
    {
      "@search.text": "Nice <em>Hotel</em>",
      "description": "Cheapest hotel in town",
      "docId": "1",
      "title": "Nice Hotel"
    },
    {
      "@search.text": "Fancy <em>Hotel</em>",
      "description": "Best hotel in town",
      "docId": "2",
      "title": "Fancy Hotel"
    }
  ]
}

定義

名稱	Description
Accept	接受標頭。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細資料。
ErrorResponse	所有 Azure Resource Manager API 的常見錯誤回應，以傳回失敗作業的錯誤詳細數據。（這也遵循 OData 錯誤回應格式。）。
SuggestDocumentsResult	包含來自索引之建議查詢結果的回應。
SuggestResult	結果，其中包含建議查詢所找到的檔，加上相關聯的元數據。

Accept

列舉型別

接受標頭。

值	Description
application/json;odata.metadata=none

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱	類型	Description
info		其他資訊。
type	string	其他信息類型。

ErrorDetail

Object

錯誤詳細資料。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤的其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳情
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

所有 Azure Resource Manager API 的常見錯誤回應，以傳回失敗作業的錯誤詳細數據。（這也遵循 OData 錯誤回應格式。）。

名稱	類型	Description
error	ErrorDetail	error 物件。

SuggestDocumentsResult

Object

包含來自索引之建議查詢結果的回應。

名稱	類型	Description
@search.coverage	number (double)	指出查詢中包含的索引百分比的值，如果要求中未設定 minimumCoverage，則為 Null。
value	SuggestResult[]	查詢所傳回的結果序列。

SuggestResult

Object

結果，其中包含建議查詢所找到的檔，加上相關聯的元數據。

名稱	類型	Description
@search.text	string	建議結果的文字。