Documents - Autocomplete Post

服務:: Search Service

API 版本:: 2026-04-01

根據索引中的輸入文字和相符字詞自動完成不完整的查詢字詞。

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

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string (uri)	搜尋服務的端點 URL。
indexName	path	True	string	索引的名稱。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。

要求標頭

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

要求本文

名稱	必要	類型	Description
search	True	string	要建立自動完成結果基礎的搜尋文字。
suggesterName	True	string	建議工具的名稱，如建議工具集合中所指定，屬於索引定義的一部分。
autocompleteMode		AutocompleteMode	指定自動完成的模式。預設值為 'oneTerm'。使用 'twoTerms' 取得 Shingles，並使用 'oneTermWithContext' 使用目前的內容，同時產生自動完成的字詞。
filter		string	一種 OData 運算式，可篩選用來產生自動完成結果的完整字詞的文件。
fuzzy		boolean	指出是否要對自動完成查詢使用模糊比對的值。預設值為 false。當設定為 true 時，即使搜尋文字中有替換或遺漏的字元，查詢也會自動完成字詞。雖然這在某些情況下提供了更好的體驗，但它會帶來效能成本，因為模糊自動完成查詢速度較慢且消耗更多資源。
highlightPostTag		string	附加至叫用醒目提示的字串標記。必須使用 highlightPreTag 進行設定。如果省略，點擊突出顯示將被禁用。
highlightPreTag		string	在叫用醒目提示前面加上的字串標記。必須使用 highlightPostTag 進行設定。如果省略，點擊突出顯示將被禁用。
minimumCoverage		number (double)	介於 0 到 100 之間的數字，指出自動完成查詢必須涵蓋的索引百分比，才能將查詢報告為成功。此參數對於確保搜尋可用性，即使是只有一個複本的服務，也很有用。預設值為 80。
searchFields		string	查詢自動完成字詞時要考慮的以逗點分隔的欄位名稱清單。目標欄位必須包含在指定的建議器中。
top		integer (int32)	要擷取的自動完成字詞數目。這必須是介於 1 到 100 之間的值。預設值為 5。

回應

名稱	類型	Description
200 OK	AutocompleteResult	要求已成功。
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

範例

SearchIndexAutocompleteDocumentsPost

範例要求

HTTP

POST https://exampleservice.search.windows.net/indexes('example-index')/docs/search.post.autocomplete?api-version=2026-04-01


{
  "search": "p",
  "autocompleteMode": "oneTerm",
  "filter": "ownerId ne '1'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "searchFields": "category, ownerId",
  "suggesterName": "sg",
  "top": 10
}

範例回覆

狀態碼:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "text": "purple",
      "queryPlusText": "<em>purple</em>"
    },
    {
      "text": "pink",
      "queryPlusText": "<em>pink</em>"
    }
  ]
}

定義

名稱	Description
Accept	接受標頭。
AutocompleteItem	自動完成要求的結果。
AutocompleteMode	指定自動完成的模式。預設值為 'oneTerm'。使用 'twoTerms' 取得帶狀皰疹，並使用 'oneTermWithContext' 使用目前的內容來產生自動完成字詞。
AutocompleteRequest	模糊比對和其他自動完成查詢行為的參數。
AutocompleteResult	自動完成查詢的結果。
ErrorAdditionalInfo	資源管理錯誤附加資訊。
ErrorDetail	錯誤詳細資料。
ErrorResponse	所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。（這也遵循 OData 錯誤回應格式。）。

Accept

列舉型別

接受標頭。

值	Description
application/json;odata.metadata=none

AutocompleteItem

Object

自動完成要求的結果。

名稱	類型	Description
queryPlusText	string	查詢以及已完成的字詞。
text	string	已完成的字詞。

AutocompleteMode

列舉型別

指定自動完成的模式。預設值為 'oneTerm'。使用 'twoTerms' 取得帶狀皰疹，並使用 'oneTermWithContext' 使用目前的內容來產生自動完成字詞。

值	Description
oneTerm	只建議一個術語。如果查詢有兩個詞彙，則只會完成最後一個詞彙。例如，如果輸入是「華盛頓醫務人員」，則建議的術語可能包括「醫療補助」、「醫療保險」和「藥物」。
twoTerms	將建議匹配索引中的兩個術語短語。例如，如果輸入是「醫療人員」，則建議的字詞可能包括「醫療保險承保範圍」和「醫療助理」。
oneTermWithContext	完成具有兩個以上字詞的查詢中的最後一個字詞，其中最後兩個字詞是索引中存在的片語。例如，如果輸入是「華盛頓醫療」，則建議的術語可能包括「華盛頓醫療補助」和「華盛頓醫療」。

AutocompleteRequest

Object

模糊比對和其他自動完成查詢行為的參數。

名稱	類型	Description
autocompleteMode	AutocompleteMode	指定自動完成的模式。預設值為 'oneTerm'。使用 'twoTerms' 取得 Shingles，並使用 'oneTermWithContext' 使用目前的內容，同時產生自動完成的字詞。
filter	string	一種 OData 運算式，可篩選用來產生自動完成結果的完整字詞的文件。
fuzzy	boolean	指出是否要對自動完成查詢使用模糊比對的值。預設值為 false。當設定為 true 時，即使搜尋文字中有替換或遺漏的字元，查詢也會自動完成字詞。雖然這在某些情況下提供了更好的體驗，但它會帶來效能成本，因為模糊自動完成查詢速度較慢且消耗更多資源。
highlightPostTag	string	附加至叫用醒目提示的字串標記。必須使用 highlightPreTag 進行設定。如果省略，點擊突出顯示將被禁用。
highlightPreTag	string	在叫用醒目提示前面加上的字串標記。必須使用 highlightPostTag 進行設定。如果省略，點擊突出顯示將被禁用。
minimumCoverage	number (double)	介於 0 到 100 之間的數字，指出自動完成查詢必須涵蓋的索引百分比，才能將查詢報告為成功。此參數對於確保搜尋可用性，即使是只有一個複本的服務，也很有用。預設值為 80。
search	string	要建立自動完成結果基礎的搜尋文字。
searchFields	string	查詢自動完成字詞時要考慮的以逗點分隔的欄位名稱清單。目標欄位必須包含在指定的建議器中。
suggesterName	string	建議工具的名稱，如建議工具集合中所指定，屬於索引定義的一部分。
top	integer (int32)	要擷取的自動完成字詞數目。這必須是介於 1 到 100 之間的值。預設值為 5。

AutocompleteResult

Object

自動完成查詢的結果。

名稱	類型	Description
@search.coverage	number (double)	值，指出自動完成要求所考慮的索引百分比，如果要求中未指定minimumCoverage，則為 null。
value	AutocompleteItem[]	傳回的自動完成項目清單。

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	錯誤物件。