Azure AI 搜尋服務 REST API (自動完成)

發行項
02/28/2024

自動完成 API 會使用搜尋索引中的現有字詞完成部分類型查詢輸入，以用於次要查詢。例如，如果查詢輸入為 "medic"，則如果這些詞彙位於索引中，則 Autocomplete API 會"medicare"傳回、 "medicaid""medicine" 。在內部，搜尋引擎會在已設定 建議工具 的欄位中尋找相符的字詞。

服務要求需要使用 HTTPS。您可以使用 GET 或 POST 方法來建構 自動完成 要求。

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

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

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

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

URI 參數

參數	Description
[服務名稱]	必要。將此設定為搜尋服務的唯一用戶定義名稱。
[索引名稱]/docs	必要。指定具名索引的檔集合。
api-version	必要。如需支援的版本清單，請參閱 API 版本。針對查詢，api-version 一律會指定為 GET 和 POST 的 URI 參數。

URL 編碼建議

直接呼叫 GET REST API 時，請記得 URL 編碼特定的查詢參數。針對 自動完成，下列查詢參數可能需要 URL 編碼：

搜尋
$filter
highlightPreTag
highlightPostTag

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

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

要求標頭

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

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，並在要求上提供持有人令牌，則為選擇性，否則需要密鑰。針對集合的 `docs` 查詢要求可以指定系統管理員金鑰或查詢金鑰做為 `api-key`。查詢索引鍵用於索引檔集合上的唯讀作業。如需詳細資訊，請參閱使用密鑰驗證連線到 Azure AI 搜尋服務。

要求本文

針對 GET：None。

針對 POST：

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "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),
  "search": "partial_search_input",  
  "searchFields": "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 呼叫 Autocomplete，api-version 都會指定為 URI 參數。
autocompleteMode	字串	選擇性。預設為 oneTerm。有效值為 oneTerm、twoTerms、oneTermWithContext。 oneTerm 會傳回單一字詞。如果查詢有兩個詞彙，則只會完成最後一個字詞。例如，假設有 `"washington medic"`，回應可能是下列任何一個單一字詞：`"medicaid"`、、`"medicare""medicine"`。 twoTerms 會比對索引中的兩個詞彙詞組。例如，假設有 `"medic"`，回應可能是 `"medicare coverage"`或 `"medical assistant"`。在許多情況下，單一字詞 `"medicare"` 或 `"medical"` 不會傳回，因為喜好設定會提供給符合的兩個詞彙片語。 oneTermWithContext 會以兩個或多個字詞完成查詢中的最後一個字詞，其中最後兩個詞彙是索引中存在的詞組。例如，假設有 `"washington medic"`，回應可能是 `"washington medicaid"`、 `"washington medical"`。
$filter	字串	選擇性。標準 OData 語法中的結構化搜尋表示式，可篩選考慮用來產生已完成字詞建議的檔。自動完成 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，而不是 #) 。
minimumCoverage	整數	選擇性。預設值為80。介於 0 到 100 之間的數位，表示索引的百分比必須可供服務查詢，才能回報為成功。預設值會反映對完整涵蓋範圍速度與效率的偏差。減少涵蓋範圍會限制查詢擴充，讓結果能夠更快返回。它也允許查詢在部分索引可用性上成功，即使一個分區因服務健康情況問題或索引維護而回應緩慢或無法使用也一樣。不論 minimumCoverage 的值為何，該索引百分比都必須可用，否則自動完成會傳回 HTTP 狀態代碼 503。如果 Autocomplete 在 minimumCoverage 層級成功，它會傳回 HTTP 200，並在 @search.coverage 回應中包含值，指出服務查詢時可用的索引百分比。如果發生 503 錯誤，降低此值可能會很有説明。否則，如果回應提供的相符專案不足，您可能會考慮引發值。
搜尋	字串	必要。要搜尋的文字。要完成的搜尋文字。必須至少 1 個字元，而且不能多於 100 個字元。它不能包含運算子、查詢語法或引號片語語。
searchFields	字串	選擇性。用來搜尋指定搜尋文字的逗號分隔欄位名稱清單。目標欄位必須列在索引中的建議工具定義中。
suggesterName	字串	必要。建議工具的名稱，如建議工具集合中所指定，屬於索引定義的一部分。建議工具會決定掃描哪些欄位是否有建議的查詢字詞。
$top	整數	選擇性。預設值為 5。要擷取的自動完成建議數目。值必須是 1 到 100 之間的數字。使用 POST 呼叫時，此參數會命名為 top，而不是$top。

(1) 自動完成中的模糊限制：

首先，編輯距離僅限於每個標記的一個字元差異，與搜尋中的模糊參數不同。將編輯距離上限設為一個字元，表示不會找到所有候選相符專案，但必須有上限，才能確保可接受的效能層級。

其次，模糊步驟會在部分令牌展開之後發生，而且只會考慮來自相同索引分區的詞彙來進行模糊比對。此條件約束會藉由排除所有分區的模糊相符項目匯總，來增加自動完成API的效能。當索引中新增更多詞彙時，此條件約束會變得較不明顯，因此會為每個分區產生類似的字詞分佈。隨著詞彙平均散發，分區內的模糊比對是整個索引中模糊相符專案的良好近似值。不過，如果索引的詞彙較少，例如在測試或原型索引中，則結果可能會推斷結果，導致跨分區表示不平均。如需如何將索引分割成分區的詳細資訊，請參閱數據分割和複本組合。

回應

狀態代碼：成功回應時會傳回「200 OK」。。

回應承載有兩個屬性。

屬性	Description
"text"	完成的字詞或片語
“queryPlusText”	初始查詢輸入加上已完成的字詞或片語

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

範例

範例 1： 擷取三個自動完成建議，其中部分搜尋輸入具有 'washington medic' 預設模式， (oneTerm) ：

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

回應：

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

範例 2：擷取部分搜尋輸入為 'washington medic' 和 autocompleteMode=twoTerms的三個自動完成建議：

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

回應：

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

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