Documents - Suggest Post

服務:
Search Service
API 版本:
2026-04-01

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

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?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

要用來建議檔的搜尋文字。 必須至少有 1 個字元，且不超過 100 個字元。
suggesterName True

string

建議工具的名稱，如建議工具集合中所指定，屬於索引定義的一部分。
filter

string

一個 OData 運算式，可篩選考慮建議的文件。
fuzzy

boolean

指出是否要針對建議查詢使用模糊比對的值。 預設值為 false。 設定為 true 時，即使搜尋文字中有替換或遺漏的字元，查詢也會尋找建議。 雖然這在某些情況下提供了更好的體驗，但它會以效能成本為代價，因為模糊建議搜尋速度較慢且消耗更多資源。
highlightPostTag

string

附加至叫用醒目提示的字串標記。 必須使用 highlightPreTag 進行設定。 如果省略，則會停用建議的點擊醒目提示。
highlightPreTag

string

在叫用醒目提示前面加上的字串標記。 必須使用 highlightPostTag 進行設定。 如果省略，則會停用建議的點擊醒目提示。
minimumCoverage

number (double)

介於 0 到 100 之間的數字，表示建議查詢必須涵蓋的索引百分比，才能將查詢報告為成功。 此參數對於確保搜尋可用性，即使是只有一個複本的服務，也很有用。 預設值為 80。
orderby

string

以逗號分隔的 OData 清單$orderby用來排序結果的運算式。 每個運算式可以是功能變數名稱或對 geo.distance（） 或 search.score（） 函式的呼叫。 每個表達式後面可以接著 asc 表示遞增，或 desc 表示遞減。 預設值為遞增順序。 系結會因檔比對分數而中斷。 如果未指定任何$orderby，則預設排序順序會依檔比對分數遞減。 最多可以有 32 個$orderby子句。
searchFields

string

以逗點分隔的欄位名稱清單，以搜尋指定的搜尋文字。 目標欄位必須包含在指定的建議器中。
select

string

要擷取的欄位以逗點分隔的清單。 如果未指定，則只會在結果中包含索引鍵欄位。
top

integer (int32)

要擷取的建議數目。 這必須是介於 1 到 100 之間的值。 預設值為 5。

回應

名稱 類型 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

範例

SearchIndexSuggestDocumentsPost

範例要求

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


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

範例回覆

狀態碼:
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"
    }
  ]
}

定義

名稱 Description
Accept

接受標頭。
ErrorAdditionalInfo

資源管理錯誤附加資訊。
ErrorDetail

錯誤詳細資料。
ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。 （這也遵循 OData 錯誤回應格式。）。
SuggestDocumentsResult

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

篩選、排序、模糊比對和其他建議查詢行為的參數。
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

錯誤物件。

SuggestDocumentsResult

Object

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

名稱 類型 Description
@search.coverage

number (double)

指出查詢中包含的索引百分比的值，如果要求中未設定 minimumCoverage，則為 Null。
value

SuggestResult[]

查詢所傳回的結果序列。

SuggestRequest

Object

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

名稱 類型 Description
filter

string

一個 OData 運算式，可篩選考慮建議的文件。
fuzzy

boolean

指出是否要針對建議查詢使用模糊比對的值。 預設值為 false。 設定為 true 時，即使搜尋文字中有替換或遺漏的字元，查詢也會尋找建議。 雖然這在某些情況下提供了更好的體驗，但它會以效能成本為代價，因為模糊建議搜尋速度較慢且消耗更多資源。
highlightPostTag

string

附加至叫用醒目提示的字串標記。 必須使用 highlightPreTag 進行設定。 如果省略，則會停用建議的點擊醒目提示。
highlightPreTag

string

在叫用醒目提示前面加上的字串標記。 必須使用 highlightPostTag 進行設定。 如果省略，則會停用建議的點擊醒目提示。
minimumCoverage

number (double)

介於 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 (int32)

要擷取的建議數目。 這必須是介於 1 到 100 之間的值。 預設值為 5。

SuggestResult

Object

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

名稱 類型 Description
@search.text

string

建議結果的文字。