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

[アーティクル]
03/05/2024

オートコンプリート 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 パラメーター

パラメーター	説明
[サービス名]	必須。これを検索サービスの一意のユーザー定義名に設定します。
[インデックス名]/docs	必須。名前付きインデックスの documents コレクションを指定します。
api-version	必須。サポートされているバージョンの一覧については、「API のバージョン」を参照してください。クエリの場合、API バージョンは常に GET と POST の両方の URI パラメーターとして指定されます。

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

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

search
$filter
highlightPreTag
highlightPostTag

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

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

要求ヘッダー

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

フィールド説明

Content-Type 必須。これを application/json

api-key Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。コレクションに docs 対するクエリ要求では、admin-key または query-key のいずれかをとして api-key指定できます。クエリキーは、インデックスドキュメントコレクションに対する読み取り専用操作に使用されます。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

フィールド	説明
Content-Type	必須。これを `application/json`
api-key	Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。コレクションに `docs` 対するクエリ要求では、admin-key または query-key のいずれかをとして `api-key`指定できます。クエリキーは、インデックスドキュメントコレクションに対する読み取り専用操作に使用されます。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

要求本文

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 の間で多少異なります。これらの違いは、以下に該当します。

名前	型	説明
api-version	string	必須。要求に使用される REST API のバージョン。サポートされているバージョンの一覧については、「API のバージョン管理」を参照してください。この操作では、GET と POST のどちらを使用してオートコンプリートを呼び出すかに関係なく、API バージョンが URI パラメーターとして指定されます。
autocompleteMode	string	省略可能。既定値は oneTerm です。有効な値は、oneTerm、twoTerms、oneTermWithContext です。 oneTerm は 1 つの用語を返します。クエリに 2 つの用語がある場合は、最後の用語のみが完了します。たとえば、を指定すると `"washington medic"`、応答は、次の 1 つの用語のいずれかである場合があります: `"medicaid"`、 `"medicare"`、 `"medicine"`。 twoTerms は、インデックス内の 2 つの用語の語句に一致します。たとえば、を指定すると`"medic"`、応答は、、または `"medical assistant"`になります`"medicare coverage"`。多くの場合、一致する 2 つの用語 `"medicare"` の語句に優先設定が与えられるため、単一の用語または `"medical"` が返されません。 oneTermWithContext は、クエリの最後の用語を 2 つ以上の用語で完了します。最後の 2 つの用語はインデックスに存在する語句です。たとえば、を指定すると`"washington medic"`、応答は、になります`"washington medical""washington medicaid"`。
$filter	string	省略可能。完成した用語候補を生成するために考慮されたドキュメントをフィルター処理する、標準の OData 構文の構造化検索式。オートコンプリート API では、フィルター式 "search.ismatch" と "search.ismatchscoring*" はサポートされていません。フィルターで使用できるのは、フィルター可能なフィールドのみです。 POST で呼び出されると、このパラメーターは$filterではなく filter という名前になります。 Azure AI Search がサポートする OData 式文法のサブセットの詳細については、「Azure AI Search の OData 式構文」を参照してください。
あいまい一致	boolean	任意。既定値は false です。 true に設定すると、検索テキスト ⁽¹⁾ に置換または欠落した文字がある場合でも、この API は候補を検索します。これにより、一部のシナリオではエクスペリエンスが向上しますが、あいまい候補の検索が遅くなり、より多くのリソースを消費するため、パフォーマンスコストがかかります。
highlightPostTag	string	省略可能。空の文字列を既定値に設定します。強調表示された用語に追加する文字列タグ。 highlightPreTag を使用して設定する必要があります。 URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。 GET を使用して呼び出す場合、URL 内の予約文字はパーセントエンコードされている必要があります (たとえば、#の代わりに %23)。
highlightPreTag	string	省略可能。空の文字列を既定値に設定します。強調表示された用語の先頭に付加する文字列タグ。 highlightPostTag を使用して設定する必要があります。 GET を使用して呼び出す場合、URL 内の予約文字はパーセントエンコードされている必要があります (たとえば、#の代わりに %23)。
minimumCoverage	整数 (integer)	省略可能。既定値は 80 です。 0 ~ 100 の範囲の数値は、クエリを成功として報告する前にクエリを処理するために使用できるインデックスの割合を示します。既定では、完全なカバレッジに対する速度と効率に対するバイアスが反映されます。カバレッジを減らすと、クエリの拡張が制限され、結果が速く戻ることができます。また、サービス正常性の問題やインデックスのメンテナンスのために 1 つのシャードの応答が遅い場合や使用できない場合でも、部分的なインデックスの可用性に対してクエリを成功させることができます。 minimumCoverage の値に関係なく、インデックスのその割合を使用できる必要があります。または Autocomplete は HTTP 状態コード 503 を返します。 Autocomplete が minimumCoverage レベルで成功した場合、HTTP 200 が返され、クエリの処理時に使用できたインデックスの割合を示す値が応答に含まれます @search.coverage 。この値を小さくすると、503 エラーが発生している場合に役立つ場合があります。それ以外の場合は、応答で不十分な一致が提供されている場合は、値を上げることを検討してください。
search	string	必須。検索するテキストです。完了する検索テキスト。 1 文字以上 100 文字以下で指定する必要があります。演算子、クエリ構文、または引用符で囲まれた語句を含めることはできません。
searchFields	string	省略可能。指定された検索テキストを検索するための、コンマ区切りのフィールド名の一覧。ターゲットフィールドは、インデックスの Suggesters 定義に一覧表示する必要があります。
suggesterName	string	必須。インデックス定義の一部である Suggesters コレクションで指定された suggester の名前。 suggester は、提案されたクエリ用語に対してスキャンされるフィールドを決定します。
$top	整数 (integer)	省略可能。既定値は 5 です。取得するオートコンプリート候補の数。値は 1 ～ 100 の数値である必要があります。 POST で呼び出されると、このパラメーターの名前は、$topではなく top になります。

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

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

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

Response

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

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

プロパティ	説明
"text"	完了した用語または語句
"queryPlusText"	最初のクエリ入力と、完了した用語または語句

{  
  "@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 が必要であることに注意してください。

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

URI パラメーター

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

要求ヘッダー

要求本文

クエリパラメーター

Response

例

こちらもご覧ください

その他のリソース

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

URI パラメーター

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

要求ヘッダー

要求本文

クエリ パラメーター

Response

例

こちらもご覧ください

その他のリソース

クエリパラメーター