提案 (Azure AI Search REST API)

[アーティクル]
11/13/2023

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]

ドキュメント検索要求とは対照的に、Suggestions 呼び出しをキーボード入力にバインドする場合と、検索呼び出しがクリックイベントにバインドされる場合があります。

GET を使用して呼び出された場合、要求 URL の長さは 8 KB を超えることはできません。通常、この長さはほとんどのアプリケーションで十分です。ただし、一部のアプリケーションでは、特に OData フィルター式が使用される場合に、非常に大きなクエリが生成されます。これらのアプリケーションでは、HTTP POST は GET よりも大きなフィルターを許可するため、より優れた選択肢です。

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

URI パラメーター

パラメーター	説明
[サービス名]	必須。これを検索サービスの一意のユーザー定義名に設定します。
[インデックス名]/docs	必須。名前付きインデックスの documents コレクションを指定します。
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 AI Search .NET クライアントライブラリを使用して URL エンコードを処理する場合は、URL エンコードは必要ありません。

要求ヘッダー

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

フィールド説明

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

api-key Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。ドキュメントコレクションに対するクエリ要求では、API キーとして管理者キーまたはクエリキーを指定できます。クエリキーは、ドキュメントコレクションに対する読み取り専用操作に使用されます。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

フィールド	説明
Content-Type	必須。これを `application/json`
api-key	Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。ドキュメントコレクションに対するクエリ要求では、API キーとして管理者キーまたはクエリキーを指定できます。クエリキーは、ドキュメントコレクションに対する読み取り専用操作に使用されます。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

要求本文

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

名前	型	説明
api-version	string	必須。要求に使用される REST API のバージョン。サポートされているバージョンの一覧については、「API のバージョン」を参照してください。この操作では、API バージョンは、GET と POST のどちらを使用して API を呼び出すかに関係なく、URL のクエリパラメーターとして指定されます。
$filter	string	省略可能。検索候補と見なされるドキュメントをフィルター処理する式。フィルターで使用できるのは、フィルター可能なフィールドのみです。オートコンプリート API では、フィルター式 "search.ismatch" と "search.ismatchscoring*" はサポートされていません。 POST で呼び出されると、このパラメーターは$filterではなく filter という名前になります。 Azure AI Search がサポートする OData 式文法のサブセットの詳細については、「Azure AI Search の OData 式構文」を参照してください。
あいまい一致	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 を返します。 Suggestions が minimumCoverage レベルで成功した場合、HTTP 200 が返され、クエリの処理時に使用できたインデックスの割合を示す値が応答に含まれます @search.coverage 。この値を小さくすると、503 エラーが発生している場合に役立つ場合があります。それ以外の場合は、応答が不十分な一致を提供している場合は、値を上げることを検討できます。
search	string	必須。クエリの候補を示すために使用する検索テキスト。 1 文字以上 100 文字以下で指定する必要があります。演算子、クエリ構文、または引用符で囲まれた語句を含めることはできません。
searchFields	string	省略可能。指定された検索テキストを検索するための、コンマ区切りのフィールド名の一覧。ターゲットフィールドは、インデックスの Suggesters 定義に一覧表示する必要があります。
$select	string	省略可能。取得するフィールドの一覧で、コンマで区切ります。指定しない場合は、ドキュメントキーと提案テキストのみが返されます。このパラメーターを `*`に設定することによって、明示的にすべてのフィールドを要求することができます。 POST を使用してを呼び出す場合、このパラメーターには、$selectではなく select という名前が付けられます。
suggesterName	string	必須。インデックス定義の一部である Suggesters コレクションで指定された suggester の名前。 suggester は、推奨されるクエリ用語に対してスキャンされるフィールドを決定します。
$top	整数 (integer)	省略可能。既定値は 5)。取得するオートコンプリート候補の数。値は 1 ～ 100 の数値である必要があります。 POST を使用してを呼び出す場合、このパラメーターの名前は、$topではなく top になります。

Response

状態コード: 正常に応答するために "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"  
    }

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

提案 (Azure AI Search REST API)

URI パラメーター

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

要求ヘッダー

要求本文

クエリパラメーター

Response

例

こちらもご覧ください

その他のリソース

提案 (Azure AI Search REST API)

URI パラメーター

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

要求ヘッダー

要求本文

クエリ パラメーター

Response

例

こちらもご覧ください

その他のリソース

クエリパラメーター