オートコンプリート (Azure AI Search REST API)

オートコンプリート API は、セカンダリ クエリで使用するために、検索インデックス内の既存の用語を使用して、部分的に型指定されたクエリ入力を完了します。 たとえば、クエリ入力が の場合、Autocomplete API は"medic"、これらの用語がインデックス内にある場合、 を"medicaid""medicine"返"medicare"します。 内部的には、検索エンジンは Suggester が構成されているフィールドで一致する用語を検索します。

サービス要求には 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 要求のサイズ制限がほぼ 16 MB であるため、POST を使用する場合は、フィルター文字列のサイズそのものではなく、フィルターに含まれる句の数が制限要因になります。 POST 要求サイズの制限が非常に大きい場合でも、フィルター式を任意に複雑にすることはできません。 フィルターの複雑さの制限の詳細については、「 Azure AI Search の OData 式構文」を参照してください。

URI パラメーター

URL エンコードに関する推奨事項

GET REST API を直接呼び出すときは、必ず URL エンコード 固有のクエリ パラメーターを使用してください。 オートコンプリートの場合は、次のクエリ パラメーターに URL エンコードが必要になる場合があります。

• search
• $filter
• highlightPreTag
• highlightPostTag

URL エンコードは、個々のパラメーターにのみ推奨されます。 クエリ文字列全体 (? の後の全部) を気付かずに URL エンコードした場合、要求が壊れます。

また、URL エンコードは、GET を使用して REST API を直接呼び出すときにのみ必要です。 POST を使用する場合や、エンコードを処理する Azure AI Search .NET クライアント ライブラリを使用する場合は、URL エンコードは必要ありません。

要求ヘッダー

次の表では、必須と省略可能の要求ヘッダーについて説明します。

要求本文

GET の場合: なし。

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 上のいくつかのパラメーターを受け入れ、POST で呼び出された場合は要求本文の JSON プロパティとして受け入れます。 いくつかのパラメーターの構文は、GET および POST の間で多少異なります。 これらの違いは、以下に該当します。

(1) オートコンプリートにおけるファジーの制限事項:

まず、 検索のあいまいパラメーターとは異なり、編集距離はトークンごとに 1 文字の差のみに制限されます。 編集距離を 1 文字に制限すると、すべての候補の一致が見つかるわけではありませんが、許容されるレベルのパフォーマンスを確保するにはキャップが必要です。

次に、あいまいステップは部分的なトークン展開の後に行われ、同じインデックス シャードからの用語のみがあいまい一致と見なされます。 この制約により、すべてのシャードに対するあいまい一致の集計を排除することで、Autocomplete API のパフォーマンスが向上します。 この制約は、インデックスに追加される用語が増えるにつれて目立たなくなり、シャードごとに同様の用語分布が生成されます。 用語は均等に分散されるため、シャード内のあいまい一致は、インデックス全体のあいまい一致の近似値として適しています。 ただし、テストインデックスやプロトタイプインデックスなど、インデックスの用語が少ない場合、結果は劣る可能性があり、シャード間で不均一な表現が発生します。 インデックスをシャードに分割する方法の詳細については、「 パーティションとレプリカの組み合わせ」を参照してください。

Response

状態コード: 正常な応答のために "200 OK" が返されます。

応答ペイロードには、2 つのプロパティがあります。

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

例

例 1: 部分検索入力 'washington medic' が既定モード (oneTerm) の 3 つのオートコンプリート候補を取得します。

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が と である 3 つのオートコンプリート候補を取得します。

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"
    }
  ]
}  

オートコンプリート操作では suggesterName が必要であることに注意してください。

こちらもご覧ください

• インデックスに suggesters を追加する
• 提案またはオートコンプリートをアプリケーションに追加する
• HTTP 状態コード