候補 (Azure Cognitive Search REST API)

Suggestions 要求は、suggester 対応フィールドで一致する値を検索し、一致するドキュメントを返す、入力としての検索クエリです。 たとえば、 都市 フィールドで提案を有効にした場合、「sea」と入力すると、そのフィールドの "Seattle"、"Sea Tac"、"Seaside" (すべての実際の都市名) を含むドキュメントが生成されます。

応答は、一致するドキュメントのコンテンツとドキュメント キーです。 セカンダリ クエリで使用される完全な用語または語句を返すオートコンプリートとは対照的に、この要求は実際のドキュメントに解決される情報を返します。 一致する用語または語句がドキュメント間で同一の場合、一致するコンテンツが繰り返されます。 結果の構造を改善するには、フィルターを使用して、より多くの差別化とコンテキストを $select 提供する追加のフィールドを返すようにすることを検討してください。

サービス要求には HTTPS が必要です。 Suggest 要求は、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 Documents 要求とは対照的に、Suggestions 呼び出しをキーボード入力にバインドすることもできますが、検索呼び出しはクリック イベントにバインドされる可能性があります。

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 エンコード することを忘れないでください。 Suggestions 操作の場合、以下が含まれます。

  • search
  • $filter
  • highlightPreTag
  • highlightPostTag

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

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

要求ヘッダー

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

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

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

要求本文

GET の場合: なし。

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

名前 Type 説明
api-version string 必須。 要求に使用される REST API のバージョン。 サポートされているバージョンの一覧については、API の バージョンを参照してください。 この操作では、API を GET と POST のどちらを使用して呼び出すかに関係なく、API バージョンが URL のクエリ パラメーターとして指定されます。
$filter string 省略可能。 検索候補と見なされるドキュメントをフィルター処理する式。 フィルターで使用できるのは、フィルター可能なフィールドだけです。 オートコンプリート API では、フィルター式 "search.ismatch" と "search.ismatchscoring*" はサポートされていません。 POST を指定して呼び出すと、このパラメーターは$filterではなく filter という名前になります。 サポートされている OData 式文法のサブセットの詳細については、Azure Cognitive Searchの OData 式構文Azure Cognitive Search参照してください。
あいまい一致 boolean 任意。 既定値は false です。 true に設定すると、検索テキストに置換文字または欠落文字がある場合でも、この API は候補を検索します。 編集距離は、クエリ文字列ごとに 1 です。 クエリ文字列が複数の用語である場合は、文字列全体に 1 つの欠落文字、余分な文字、置換文字、または入れ替え文字しか存在できません。 あいまい一致を有効にすると、一部のシナリオではエクスペリエンスが向上する可能性があります。あいまい検索の検索が遅くなり、より多くのリソースを消費するため、パフォーマンス コストが発生します。
highlightPostTag string 省略可能。 空の文字列を既定値に設定します。 強調表示された用語に追加する文字列タグ。 highlightPreTag を使用して設定する必要があります。 URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。 GET を使用して呼び出す場合、URL 内の予約文字はパーセントエンコードされている必要があります (たとえば、#の代わりに %23)。
highlightPreTag string 省略可能。 空の文字列を既定値に設定します。 強調表示された用語の前に付加される文字列タグ。 highlightPostTag を使用して設定する必要があります。 GET を使用して呼び出す場合、URL 内の予約文字はパーセントエンコードする必要があります (たとえば、#の代わりに %23)。
$orderby string 省略可能。 結果を並べ替える式の一覧で、コンマで区切ります。 各式は、フィールド名または geo.distance() 関数の呼び出しです。 各式の後に "asc" (昇順) または "desc" (降順) を指定できます。 既定値は昇順です。 $orderbyには 32 個の句の制限があります。 POST で呼び出されると、このパラメーターは$orderbyではなく名前付き順序になります。
minimumCoverage 整数 (integer) 省略可能。 既定値は 80 です。 0 ~ 100 の範囲の数値。成功として報告する前にクエリの処理に使用できるインデックスの割合を示します。

既定では、完全なカバレッジに対する速度と効率に対するバイアスが反映されます。 カバレッジを減らすと、クエリの展開が制限され、結果の戻り速度が速くなります。 また、サービス正常性の問題やインデックスメンテナンスのために 1 つのシャードの応答が遅い場合や使用できない場合でも、部分的なインデックスの可用性に対してクエリを成功させることができます。

minimumCoverage の値が何であれ、インデックスのその割合を使用できる必要があります。または Suggestions は HTTP 状態コード 503 を返します。 提案が最小レベルで成功した場合、HTTP 200 が返され、クエリの処理時に使用できたインデックスの割合を示す値が応答に含まれます @search.coverage 。

この値を小さくすると、503 エラーが発生している場合に役立つ場合があります。 それ以外の場合は、応答が不十分な一致を提供している場合は、値を上げることを検討してください。
search string 必須。 クエリの候補を示すために使用する検索テキスト。 1 文字以上 100 文字以下で指定する必要があります。 演算子、クエリ構文、または引用符で囲まれた語句を含めることはできません。
searchFields string 省略可能。 指定された検索テキストを検索するための、コンマ区切りのフィールド名の一覧。 ターゲット フィールドは、インデックスの Suggesters 定義に一覧表示されている必要があります。
$select string 省略可能。 取得するフィールドの一覧で、コンマで区切ります。 指定しない場合は、ドキュメント キーと提案テキストのみが返されます。 このパラメーターを *に設定することによって、明示的にすべてのフィールドを要求することができます。 POST を使用して呼び出すとき、このパラメーターは、$selectではなく select という名前になります。
suggesterName string 必須。 インデックス定義の一部である Suggesters コレクションで指定された suggester の名前。 サジェスターは、推奨されるクエリ用語をスキャンするフィールドを決定します。
$top 整数 (integer) 省略可能。 既定値は 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"  
    }  

Suggests 操作では suggesterName が必要であることに注意してください。

関連項目