Documents - Suggest Post

服務:

Search Service

API 版本:

2024-07-01

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

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

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string	搜尋服務的端點 URL。
indexName	path	True	string	索引的名稱。
api-version	query	True	string	用戶端 API 版本。

要求標頭

名稱	必要	類型	Description
x-ms-client-request-id		string uuid	隨要求一起傳送的追蹤標識碼，以協助偵錯。

要求本文

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

回應

名稱	類型	Description
200 OK	SuggestDocumentsResult	包含符合部分輸入的建議文件回應。
Other Status Codes	ErrorResponse	錯誤回應。

範例

SearchIndexSuggestDocumentsPost

範例要求

HTTP

POST https://myservice.search.windows.net/indexes('myindex')/docs/search.post.suggest?api-version=2024-07-01

{
  "filter": "rating gt 4.0",
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "rating desc",
  "search": "hote",
  "searchFields": "title",
  "select": "docId,title,description",
  "suggesterName": "sg",
  "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
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
SuggestDocumentsResult	包含來自索引之建議查詢結果的回應。
SuggestRequest	篩選、排序、模糊比對和其他建議查詢行為的參數。
SuggestResult	結果，其中包含建議查詢所找到的檔，加上相關聯的元數據。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

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

ErrorDetail

錯誤詳細數據。

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

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

SuggestDocumentsResult

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

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

SuggestRequest

篩選、排序、模糊比對和其他建議查詢行為的參數。

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

SuggestResult

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

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