(Azure AI 搜尋 REST API) 的建議

  • 發行項

建議要求是搜尋即用類型查詢，可尋找建議工具感知欄位中的相符值，並傳回包含相符專案的檔。 例如，如果您啟用 城市 欄位的建議，輸入 「sea」 會產生包含 「Seattle」、「Sea Tac」 和 「Seaside」 的檔， (該欄位的所有實際城市名稱) 。

回應是來自相符檔加上檔索引鍵的內容。 相較于自動完成，它會傳回次要查詢中使用的已完成字詞或片語，此要求會傳回解析為實際檔的資訊。 如果檔中的相符字詞或片語相同，則會重複比對內容。 若要改善結果的結構，請考慮使用 $select 篩選來傳回提供更多差異和內容的其他欄位。

服務要求需要使用 HTTPS。 建議要求可以使用 GET 或 POST 方法來建構。

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
  Content-Type: application/json  
  api-key: [admin or query key]   

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

相較于 搜尋檔 要求，您可以將 [建議] 呼叫系結至鍵盤輸入，而 Search 呼叫可能會系結至 Click 事件。

使用 GET 呼叫時，要求 URL 的長度不能超過 8 KB。 此長度通常足以用於大部分的應用程式。 不過，某些應用程式會產生非常大的查詢，特別是使用 OData 篩選運算式時。 針對這些應用程式，HTTP POST 是較佳的選擇，因為它允許比 GET 更大的篩選。

使用 POST 時，限制因素為篩選中的子句數目，而不是原始篩選字串的大小，因為 POST 的要求大小限制約為 16 MB。 即使 POST 要求大小限制很大，篩選運算式也不能任意複雜化。 如需篩選複雜性限制的詳細資訊，請參閱 Azure AI 搜尋的 OData 運算式語法。

URI 參數

參數 Description
[服務名稱] 必要。 將此設定為搜尋服務的唯一使用者定義名稱。
[索引名稱]/docs 必要。 指定具名索引的檔集合。
api-version 必要。 目前的穩定版本是 api-version=2020-06-30 。 如需更多版本，請參閱 API 版本 。 針對查詢，api-version 一律會指定為 GET 和 POST 的 URI 參數。

URL 編碼建議

直接呼叫 GET REST API 時，請記得 URL 編碼 特定的查詢參數。 針對 建議 作業，這包括：

  • 搜尋
  • $filter
  • highlightPreTag
  • highlightPostTag

建議只針對個別參數使用 URL 編碼。 如果您不小心 URL 編碼整個查詢字串 (? 之後的所有內容)，要求將會中斷。

此外，只有在使用 GET 直接呼叫 REST API 時，才需要進行 URL 編碼。 使用 POST 呼叫 建議 時，或使用 Azure AI 搜尋 .NET 用戶端程式庫 為您處理 URL 編碼時，不需要使用 URL 編碼。

要求標頭

下表說明必要及選用的要求標頭。

欄位 Description
Content-Type 必要。 請設為 application/json
api-key 如果您使用 Azure 角色 ，並在要求上提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。 針對檔集合的查詢要求可以指定 admin-key 或 query-key 作為 API 金鑰。 查詢索引鍵用於對檔集合進行唯讀作業。 如需詳細資訊，請參閱 使用金鑰驗證連線到 Azure AI 搜尋 服務。

要求本文

針對 GET：None。

針對 POST：

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}

查詢參數

使用 GET 呼叫 URL 時，查詢會接受 URL 上的數個參數，並在使用 POST 呼叫時作為要求本文中的 JSON 屬性。 GET 和 POST 之間某些參數的語法稍有不同。 這些差異如下所述。

名稱 類型 描述
api-version 字串 必要。 用於要求的 REST API 版本。 如需支援的版本清單，請參閱 API 版本。 針對這項作業，不論您使用 GET 或 POST 呼叫 API，API 版本都會指定為 URL 中的查詢參數。
$filter 字串 選擇性。 對被視為建議的文件進行篩選的運算式。 篩選準則中只能使用可篩選的欄位。 自動完成 API 不支援篩選運算式 「search.ismatch」 和 「search.ismatchscoring*」。 使用 POST 呼叫時，此參數會命名為 filter，而不是$filter。 如需 Azure AI 搜尋所支援 OData 運算式文法子集的詳細資訊，請參閱 Azure AI 搜尋的 OData 運算式語法 。
模糊 boolean 選擇性。 預設為 False。 當設定為 true 時，即使搜尋文字中有替代字元或遺漏字元，此 API 仍會尋找建議。 編輯距離是每個查詢字串 1。 如果查詢字串是多個字詞，則整個字串中只能有一個遺漏、額外、替代或轉置字元。 在某些情況下，啟用模糊比對可能是較佳的體驗，因為模糊建議搜尋速度較慢，並耗用更多資源。
highlightPostTag 字串 選擇性。 預設為空字串。 附加至反白顯示字詞的字串標記。 必須使用 highlightPreTag 進行設定。 URL 中的保留字元必須以百分比進行編碼 (例如，%23 而不是 #)。 使用 GET 呼叫時，URL 中的保留字元必須是百分比編碼 (例如%23，而不是 #) 。
highlightPreTag 字串 選擇性。 預設為空字串。 在醒目提示字詞前面加上的字串標籤。 必須使用 highlightPostTag 來設定。 使用 GET 呼叫時，URL 中的保留字元必須以百分比編碼 (例如 %23，而不是 #) 。
$orderby 字串 選擇性。 排序結果所要依據的運算式清單 (以逗號分隔)。 每個運算式可以是一個欄位名稱，或是 geo.distance() 函式的呼叫。 每個運算式後接 「asc」 (遞增) 或 「desc」 (遞減) 。 預設值為遞增排序。 $orderby有 32 個子句的限制。 使用 POST 呼叫時，此參數會命名為 order，而不是$orderby。
minimumCoverage 整數 選擇性。 預設值為 80。 介於 0 到 100 之間的數位，指出索引的百分比必須可供服務查詢，才能回報為成功。

預設值反映完整涵蓋範圍的速度和效率偏差。 減少涵蓋範圍會限制查詢擴充，讓結果更快速返回。 它也可讓查詢在部分索引可用性上成功，即使一個分區因服務健康情況問題或索引維護而回應緩慢或無法使用也一樣。

不論 minimumCoverage 的值為何，該索引百分比都必須可用，或者建議會傳回 HTTP 狀態碼 503。 如果 Suggestions 在 minimumCoverage 層級成功，它會傳回 HTTP 200，並在 @search.coverage 回應中包含值，指出服務查詢時可用的索引百分比。

如果發生 503 錯誤，則降低此值可能會很有説明。 否則，如果回應提供的相符專案不足，您可能會考慮引發值。
搜尋 字串 必要。 要用來建議查詢的搜尋文字。 必須至少 1 個字元，而且不能多於 100 個字元。 它不能包含運算子、查詢語法或引號片語。
searchFields 字串 選擇性。 用來搜尋指定搜尋文字的逗號分隔欄位名稱清單。 目標欄位必須列在索引的 [建議工具 ] 定義中。
$select 字串 選擇性。 要擷取的欄位清單 (以逗號分隔)。 如果未指定，只會傳回檔索引鍵和建議文字。 您可以將此參數設為 *，明確地要求所有欄位。 使用 POST 呼叫時，此參數會命名為 select，而不是$select。
suggesterName 字串 必要。 建議工具的名稱，如屬於索引定義的 Suggesters 集合中所指定。 建議工具會決定要掃描哪些欄位以取得建議的查詢字詞。
$top 整數 選擇性。 預設值為 5) 。 要擷取的自動完成建議數目。 值必須是 1 到 100 之間的數字。 使用 POST 呼叫時，此參數會命名為 top，而不是$top。

回應

狀態碼：傳回 「200 OK」 以取得成功的回應。

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

如果使用預測選項來擷取欄位，這些欄位會包含在陣列的每個元素中：

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

範例

擷取部分搜尋輸入是 'lux' 的 5 個建議：

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

請注意，Suggestions 作業中需要 suggesterName 。

另請參閱