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

Autocomplete API は、セカンダリ クエリで使用するために、検索インデックス内の既存の用語を使用して、部分的に型指定されたクエリ入力を完了します。 たとえば、クエリ入力が "medic" の場合、オートコンプリート API は、それらの用語がインデックス内にある場合、"メディケア"、"メディケイド"、"medicine" を返します。 内部的には、検索エンジンは 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 Cognitive Searchの OData 式の構文に関するページを参照してください。

URI パラメーター

パラメーター 説明
[サービス名] 必須です。 これを検索サービスの一意のユーザー定義名に設定します。
[インデックス名]/docs 必須です。 名前付きインデックスのドキュメント コレクションを指定します。
api-version 必須です。 現在の安定版は.api-version=2020-06-30 その他 のバージョンについては、API のバージョン を参照してください。 クエリの場合、API バージョンは常に GET と POST の両方の URI パラメーターとして指定されます。

URL エンコードの推奨事項

GET REST API を直接呼び出すときは、特定のクエリ パラメーターを URL エンコード することを忘れないでください。 オートコンプリートの場合、次のクエリ パラメーターに URL エンコードが必要になる場合があります。

  • 検索
  • $filter
  • highlightPreTag
  • highlightPostTag

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

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

要求ヘッダー

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

フィールド 説明
Content-Type 必須です。 これを application/json
api-key 必須です。 api-key は Search サービスに対する要求の認証に使用されます。 これはサービス URL に固有の文字列値です。 コレクションに docs 対するクエリ要求では、管理キーまたはクエリ キー api-keyのいずれかを指定できます。 クエリ キーは、クエリのみの操作に使用されます。

api キーの値は、Azure portalのサービス ダッシュボードから取得できます。 詳細については、「既存の キーを検索する」を参照してください。

要求本文

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

名前 Type 説明
api-version string 必須。 要求に使用される REST API のバージョン。 サポートされているバージョンの一覧については、API の バージョン管理を参照してください。 この操作では、GET と POST のどちらを使用して Autocomplete を 呼び出すかに関係なく、API バージョンが URI パラメーターとして指定されます。
autocompleteMode string 省略可能。 既定値は oneTerm です。 有効な値は、oneTerm、twoTerm、oneTermWithContext です。

"oneTerm" は 1 つの用語を返します。 クエリに 2 つの用語がある場合、最後の用語のみが完了します。 たとえば、"washington medic" を指定すると、応答は、"メディケイド"、"メディケア"、"メディケア" のいずれかの単一の用語のいずれかになります。

"twoTerms" は、インデックス内の 2 つの語句で一致します。 たとえば、"medic" を指定すると、応答は "メディケア カバレッジ" または "医療アシスタント" である可能性があります。

"oneTermWithContext" は、2 つ以上の用語を含むクエリの最後の用語を完了します。最後の 2 つの用語はインデックスに存在する語句です。 たとえば、"washington medic" を指定すると、応答は "washington medicaid"、"washington medical" です。
$filter string 省略可能。 完成した用語候補を生成するために考慮されたドキュメントをフィルター処理する、標準の OData 構文の構造化された検索式。 オートコンプリート API では、フィルター式 "search.ismatch" と "search.ismatchscoring*" はサポートされていません。 フィルターで使用できるのは、フィルター可能なフィールドだけです。 POST を使用して呼び出すとき、このパラメーターは$filterではなく名前付きフィルターです。 サポートされている OData 式文法のサブセットの詳細については、Azure Cognitive Searchの OData 式構文Azure Cognitive Search参照してください。
あいまい一致 boolean 任意。 既定値は false です。 true に設定すると、検索テキスト (1) に置換文字または欠落文字がある場合でも、この 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 エラーが発生している場合に役立つ場合があります。 それ以外の場合は、応答が不十分な一致を提供している場合は、値を上げることを検討してください。
検索 string 必須。 検索するテキストです。 完了する検索テキスト。 1 文字以上 100 文字以下で指定する必要があります。 演算子、クエリ構文、または引用符で囲まれた語句を含めることはできません。
searchFields string 省略可能。 指定された検索テキストを検索するための、コンマ区切りのフィールド名の一覧。 ターゲット フィールドは、インデックスの Suggesters 定義に一覧表示されている必要があります。
suggesterName string 必須。 インデックス定義の一部である Suggesters コレクションで指定された suggester の名前。 サジェスターは、推奨されるクエリ用語をスキャンするフィールドを決定します。
$top 整数 (integer) 省略可能。 既定値は 5 です。 取得するオートコンプリートされた候補の数。 値は 1 ~ 100 の数値である必要があります。 POST を使用して呼び出す場合、このパラメーターは$topではなく top という名前になります。

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

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

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

Response

状態コード: "200 OK" が返され、応答が成功します。

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

プロパティ 説明
"text" 完成した用語または語句
"queryPlusText" 最初のクエリ入力と、完了した用語または語句
{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}  

例 1: 部分検索入力が既定モード (oneTerm) の "washington medic" である 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 が必要であることに注意してください。

関連項目