ドキュメントの検索 (Azure AI Search REST API)

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

クエリ要求は、検索サービス上の 1 つのインデックスのドキュメントコレクションを対象としています。一致条件を定義するパラメーターと、応答を形成するパラメーターが含まれます。 2021-04-30-Preview API バージョン以降では、インデックス名自体を使用する代わりに、インデックスエイリアスを使用して特定のインデックスをターゲットにすることもできます。

GET または POST を使用できます。クエリパラメーターは、GET 要求のクエリ文字列と POST 要求の要求本文で指定されます。

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

POST を使用している場合は、URI パラメーターとして "search" アクションを追加します。

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?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 コレクションを指定します。
[クエリパラメーター]	クエリパラメーターは、GET 要求の URI と POST 要求の要求本文で指定されます。
api-version	必須。現在の安定バージョンはです `api-version=2020-06-30`。その他のバージョンについては、「API のバージョン」を参照してください。クエリの場合、API バージョンは常に GET と POST の両方の URI パラメーターとして指定されます。

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

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

search
$filter
facet
highlightPreTag
highlightPostTag

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

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

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

部分的な検索応答の継続

Azure AI Search は、要求されたすべての結果を 1 つの検索応答で返さない場合があります。これは、$top を指定しなかったり、$top に指定した値が大きすぎたりしたために、クエリで要求したドキュメントが多すぎるなど、さまざまな理由で発生します。このような場合、Azure AI Search には、応答本文に注釈が含まれ、POST 要求の場合も@search.nextPageParameters含@odata.nextLinkまれます。これらの注釈の値を使用して別の Search 要求を作成して、検索応答の次の部分を取得できます。これは元の Search 要求の継続と呼ばれ、注釈は一般に継続トークンと呼ばれます。これらの注釈の構文と、それらが応答本文に表示される場所の詳細については、以下の応答の例を参照してください。

Azure AI Search が継続トークンを返す理由は実装固有であり、変更される可能性があります。堅牢なクライアントでは、返されたドキュメントが予想よりも少なく、ドキュメントの取得を継続するために継続トークンが含まれている場合を処理する準備が常にできている必要があります。また、継続するためには、元の要求と同じ HTTP メソッドを使用する必要がある点にも注意してください。たとえば、GET 要求を送信した場合、送信する継続の要求でも GET を使用する必要があります (POST の場合も同様です)。

注意

と @search.nextPageParameters の@odata.nextLink目的は、ページングの一般的なメカニズムを提供するためではなく、多すぎる結果を要求するクエリからサービスを保護することです。結果をページングする場合は、と $skip を一緒に使用$topします。たとえば、サイズが 10 のページが必要な場合、最初の要求にはとが$skip=0必要$top=10です。2 番目の要求には $top=10 と $skip=10が必要です。3 番目の要求には$top=10、と $skip=20が必要です。

クエリパラメーター

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

名前	型	説明
api-version	string	必須。要求に使用される REST API のバージョン。サポートされているバージョンの一覧については、「API のバージョン」を参照してください。この操作では、GET と POST のどちらを使用してドキュメントの検索を呼び出すかに関係なく、API バージョンが URI パラメーターとして指定されます。
`$count`	boolean	任意。有効な値は true または false です。既定値は "false" です。 POST を使用して呼び出されると、このパラメーターの名前はではなく `$count`count になります。結果の合計数を取得するかどうかを指定します。これは、とを無視して、検索パラメーターと$filterパラメーターに一致するすべてのドキュメントの`$top$skip`数です。この値を "true" に設定すると、パフォーマンスが低下する可能性があります。インデックスが安定している場合、カウントは正確ですが、アクティブに追加、更新、または削除されたドキュメントの下または過剰レポートが行われます。ドキュメントなしでカウントのみを取得する場合は、=0 を使用 `$top`できます。
ファセットまたはファセット	string	省略可能。ファセットの対象となるフィールド。フィールドは "ファセット可能" として属性付けされます。 GET で呼び出された場合、 `facet` はフィールド (`facet: field1`) です。 POST で呼び出されると、このパラメーターの名前 `facets` はではなく `facet` 、配列 (`facets: [field1, field2, field3]`) として指定されます。文字列には、コンマ区切りの名前と値のペアとして表されるファセットをカスタマイズするためのパラメーターを含めることができます。有効なパラメーターは、"count"、"sort"、"values"、"interval"、"timeoffset" です。 "count" はファセット用語の最大数です。既定値は 10 です。用語の数に上限はありませんが、値を大きくするとパフォーマンスが低下します。特に、ファセットフィールドに多数の一意の用語が含まれている場合は、パフォーマンスが低下します。たとえば、"facet=category,count:5" はファセット結果の上位 5 つのカテゴリを取得します。 count パラメーターが一意の用語の数より少ない場合、結果が正確でない可能性があります。これは、ファセットクエリがシャード間に分散される方法のためです。 count を 0 に設定するか、ファセット可能フィールド内の一意の値の数以上の値に設定すると、すべてのシャードで正確な数を取得できます。トレードオフは待機時間の増加です。 "sort" は"count"、"-count"、"value"、"-value" に設定できます。 count を使用して count で降順に並べ替えます。 count で昇順に並べ替えるには、-count を使用します。 value を使用して、値で昇順に並べ替えます。値で降順に並べ替えるには、-value を使用します (たとえば、"facet=category,count:3,sort:count" はファセットの上位 3 つのカテゴリを取得し、各都市名を持つドキュメントの数で降順になります)。上位 3 つのカテゴリが Budget、Motel、Luxury で、Budget が 5 ヒット、Motel が 6、Luxury が 4 の場合、バケットは Motel、Budget、Luxury の順になります。 -value の場合、"facet=rating,sort:-value" は、考えられるすべての評価のバケットを値順に降順で生成します (たとえば、評価が 1 から 5 の場合、バケットは、各評価に一致するドキュメントの数に関係なく、5、4、3、2、1 の順に並べられます)。 "values" は、ファセットエントリ値の動的なセットを指定するパイプ区切りの数値または Edm.DateTimeOffset 値に設定できます (例: "facet=baseRate,values:10 \|20" は 3 つのバケットを生成します。1 つは基本レート 0 から 10 までで、10 は含まれませんが、1 つは 20 まで、もう 1 つは 20 以上を含まない)。文字列 "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" は、2 つのバケットを生成します。1 つは 2010 年 2 月より前に改装されたホテル用、もう 1 つは 2010 年 2 月 1 日以降に改装されたホテル用です。期待される結果を得るには、値を順番に昇順で一覧表示する必要があります。 "interval" は、数値の場合は 0 より大きい整数の間隔、日付時刻の値は分、時間、日、週、月、四半期、年です。たとえば、"facet=baseRate,interval:100" は、サイズ 100 の基本レート範囲に基づいてバケットを生成します。基本レートがすべて $60 から $600 の間にある場合は、0 から 100、100 から 200、200 から 300、300-400、400 から 500、500 から 600 のバケットが存在します。文字列 "facet=lastRenovationDate,interval:year" は、ホテルが改装された年ごとに 1 つのバケットを生成します。 "timeoffset" は ([+-]hh:mm、[+-]hhmm、または [+-]hh) に設定できます。 timeoffset パラメーターを使用する場合は、Edm.DateTimeOffset 型のフィールドに適用する場合にのみ、timeoffset パラメーターを interval オプションと組み合わせる必要があります。この値によって、時間の境界の設定における UTC 時刻のオフセットを指定します。たとえば、"facet=lastRenovationDate,interval:day,timeoffset:-01:00" は、01:00:00 UTC (ターゲットタイムゾーンの午前 0 時) に始まる日の境界を使用します。 count と sort は同じファセット仕様で組み合わせることができますが、間隔または値と組み合わせることはできません。また、間隔と値を組み合わせることはできません。 timeoffset が指定されていない場合、日付時刻の間隔ファセットは UTC 時刻に基づいて計算されます。たとえば、"facet=lastRenovationDate,interval:day" の場合、日の境界は UTC の 00:00:00 から始まります。
$filter	string	省略可能。標準の OData 構文で構造化された検索式です。フィルターで使用できるのは、フィルター可能なフィールドのみです。 POST を使用してを呼び出す場合、このパラメーターは$filterではなく filter という名前になります。 Azure AI Search がサポートする OData 式文法のサブセットの詳細については、「Azure AI Search の OData 式構文」を参照してください。
highlight	string	省略可能。ヒットハイライトに使用する一連のフィールド名で、コンマで区切ります。検索可能なフィールドのみを、ヒット強調表示に使用できます。既定では、Azure AI Search はフィールドごとに最大 5 つの強調表示を返します。フィールド名の後に "-<max # の強調表示" を追加することで、>フィールドごとに制限を構成できます。たとえば、"highlight=title-3,description-10" は、タイトルフィールドから最大 3 件の強調表示されたヒットを返し、説明フィールドから最大 10 件のヒットを返します。強調表示の最大数は、1 から 1000 までの整数である必要があります。
highlightPostTag	string	任意。既定値は `"</em>"` です。強調表示された用語に追加する文字列タグ。 highlightPreTag を使用して設定する必要があります。 URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。
highlightPreTag	string	任意。既定値は `"</em>"` です。強調表示された用語の先頭に付加する文字列タグ。 highlightPostTag を使用して設定する必要があります。 URL の予約済みの文字は、パーセントでエンコードする必要があります (たとえば、# ではなく %23)。
minimumCoverage	整数 (integer)	省略可能。有効な値は 0 ~ 100 の数値で、クエリを成功として報告する前にクエリを処理するために使用できるインデックスの割合を示します。既定値は "100" です。 100% のカバレッジは、すべてのシャードが要求に応答したことを意味します (サービス正常性の問題もメンテナンスアクティビティもカバレッジが減少しません)。既定の設定では、フルカバレッジ未満では HTTP 状態コード 503 が返されます。 minimumCoverage を下げると、503 エラーが発生していて、クエリが成功する可能性を高めたい場合 (特に、1 つのレプリカに対して構成されているサービスの場合) に役立ちます。 minimumCoverage を設定し、Search が成功すると、HTTP 200 が返され、クエリに含まれていたインデックスの割合を示す値が応答に含まれます @search.coverage 。このシナリオでは、一致するすべてのドキュメントが検索結果に表示されるとは限りませんが、検索の可用性がリコールよりも重要な場合は、カバレッジを減らすことが実行可能な軽減戦略になる可能性があります。
$orderby	string	省略可能。結果を並べ替える式の一覧で、コンマで区切ります。 POST で呼び出されると、このパラメーターの名前は、$orderbyではなく orderby になります。各式には、フィールド名または geo.distance() 関数の呼び出しを指定できます。各式の後に "asc" を続けて昇順を示し、降順を示す "desc" を指定できます。並べ替えフィールドに null 値がある場合、null は最初に昇順で、最後は降順で表示されます。既定値は昇順です。結び付きは、ドキュメントの一致スコアによって切り離されます。 $orderbyが指定されていない場合、既定の並べ替え順序はドキュメント一致スコアの降順になります。 $orderbyには 32 個の句の制限があります。
queryType	string	省略可能。有効な値は "simple" または "full" です。既定値は "simple" です。 "simple" は、やなどの`+*`シンボルを許可する単純なクエリ構文を使用してクエリ文字列を`""`解釈します。クエリは、既定で各ドキュメント内のすべての検索可能なフィールド (または searchFields で示されているフィールド) で評価されます。 "full" は、完全な Lucene クエリ構文を使用してクエリ文字列を解釈します。これにより、フィールド固有の加重検索が可能になります。 Lucene クエリ言語での範囲検索は、同様の機能を提供する$filterを優先してサポートされていません。
scoringParameter	string	省略可能。 "name-value1,value2,..." の形式を使用して、スコアリング関数 (referencePointParameter など) で定義されている各パラメーターの値を示します。POST で呼び出されると、このパラメーターの名前は scoringParameter ではなく scoringParameters になります。また、各文字列が個別の名前と値のペアである文字列の JSON 配列として指定します。関数を含むスコアリングプロファイルの場合は、関数を入力リストから文字で `-` 区切ります。たとえば、という `"mylocation"` 関数は "&scoringParameter=mylocation--122.2,44.8" になります。最初のダッシュは関数名を値リストから区切り、2 番目のダッシュは最初の値 (この例では経度) の一部です。コンマを含めることができるタグブーストなどのスコアリングパラメーターの場合は、一重引用符を使用してリスト内のそのような値をエスケープできます。値自体に単一引用符が含まれる場合は、2 個入力することでエスケープできます。という名前のタグブーストパラメーター `"mytag"` があり、タグ値 "Hello, O'Brien" と "Smith" をブーストする場合、クエリ文字列オプションは "&scoringParameter=mytag-'Hello, O'Brien',Smith" になります。引用符は、コンマを含む値にのみ必要です。
scoringProfile	string	省略可能。結果を並び替えるために一致ドキュメントの一致スコアを評価するスコア付けプロファイルの名前。
scoringStatistics	string	省略可能。有効な値は "local" または "global" です。既定値は "local" です。より一貫性のあるスコアリングを行うために、ドキュメントの頻度などのスコアリング統計をグローバルに (すべてのシャードにわたって) 計算するか、待機時間を短くするためにローカル (現在のシャード) で計算するかを指定します。「Azure AI Search でのスコアリング統計」を参照してください。スコアリング統計は、あいまい検索 ('~') を使用する用語に対して常にローカルで計算されます。
search	string	省略可能。検索するテキストです。 searchFields が指定されていない限り、検索可能なすべてのフィールドが既定で検索されます。インデックスでは、検索可能なフィールド内のテキストはトークン化されるため、複数の用語を空白で区切ることができます (例: 'search=hello world')。任意の語句と一致させるには、 `` を使用します (これはブール型フィルターのクエリに便利です)。このパラメーターを省略することは、 ``に設定するのと同じ効果を持ちます。検索構文の詳細については、簡単なクエリ構文に関するページを参照してください。検索可能なフィールドに対してクエリを実行すると、結果が驚くことがあります。トークナイザには、アポストロフィや数字の中のコンマのように、英語のテキストによく使用されているケースを処理するロジックが含まれています。たとえば、'search=123,456' は、個々の用語 '123' と '456' ではなく、単一の用語 '123,456' と一致します。これは、コンマは英語の大きな数値の桁区切り記号として使用されるためです。このため、検索パラメーターで用語を区切るために句読点ではなく空白を使用することをお勧めします。
searchMode	string	省略可能。有効な値は "any" または "all" です。既定値は "any" です。一致ドキュメントをカウントする上で、検索用語の一部が一致すればよいか、それともすべて一致する必要があるかを指定します。
searchFields	string	省略可能。指定したテキストを検索するフィールド名の一覧であり、コンマで区切ります。ターゲットフィールドは、インデックススキーマで検索可能としてマークする必要があります。
$select	string	省略可能。結果セットに含めるコンマ区切りのフィールドの一覧。この句には、取得可能としてマークされたフィールドのみを含めることができます。指定しない場合、または `*`に設定した場合は、スキーマで取得可能とマークされているすべてのフィールドが含まれます。 POST を使用して呼び出されると、このパラメーターには、$selectではなく select という名前が付けられます。
sessionID	string	省略可能。 sessionId を使用すると、複数のレプリカを持つ検索サービスの関連性スコアの一貫性を向上させることができます。マルチレプリカ構成では、同じクエリに対する個々のドキュメントの関連性スコアに若干の違いがある場合があります。セッション ID が指定されると、サービスは特定の要求をそのセッションの同じレプリカにルーティングするためのベストエフォートを行います。同じセッション ID 値を繰り返し再利用すると、レプリカ間での要求の負荷分散が妨げられ、検索サービスのパフォーマンスに悪影響を及ぼす可能性があります。 sessionId として使用される値は、'_' 文字で始めることはできません。サービスにレプリカがない場合、このパラメーターはパフォーマンスやスコアの一貫性には影響しません。
$skip	整数 (integer)	省略可能。スキップする検索結果の数です。 POST で呼び出されると、このパラメーターの名前はではなく `$skip`skip になります。この値は 100,000 を超えることはできません。ドキュメントを順番にスキャンする必要があるが、この制限により使用 `$skip` できない場合は、インデックス内のすべてのドキュメントに対して一意の値を持つフィールド (たとえば、ドキュメントキーなど) に対して$orderbyを使用し、代わりに範囲クエリで$filterすることを検討してください。
$top	整数 (integer)	省略可能。取得する検索結果の数です。既定値は 50 です。 POST で呼び出されると、このパラメーターの名前はではなく `$top`top になります。 1000 より大きい値を指定し、結果が 1,000 を超える場合は、最初の 1,000 件の結果のみが、結果の次のページへのリンクと共に返されます (次の例を参照 @odata.nextLink )。 Azure AI Search では、サーバー側のページングを使用して、クエリが一度に取得するドキュメントが多すぎるのを防ぎます。既定のページサイズは 50 で、最大ページサイズは 1000 です。つまり、を指定`$top`しない場合、既定で検索ドキュメントは最大 50 件の結果を返します。結果が 50 を超える場合、応答には最大 50 件の結果の次のページを取得するための情報が含まれます (以下の例の「@odata.nextLink」および「@search.nextPageParameters」を参照してください)。同様に、に 1000 `$top` より大きい値を指定し、結果が 1,000 を超える場合は、最初の 1,000 件の結果のみが返され、最大で 1,000 件の結果の次のページを取得するための情報が返されます。

Response

状態コード: 応答の成功に対して「200 OK」が返されます。

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

例

その他の例については、「 Azure AI Search の OData 式構文」を参照してください。

日付に基づいて降順で並べ替えられたインデックスを検索します。

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

ファセット検索で、インデックスを検索し、特定の範囲の baseRate を持つカテゴリ、評価、タグ、および項目のファセットを取得します。
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
最後のファセットがサブフィールドにあることに注意してください。ファセットは親ドキュメント (Hotels) をカウントし、中間サブドキュメント (Rooms) はカウントしないため、応答によって、各価格バケットに部屋があるホテルの数が決まります。

フィルターを使用して、ユーザーが Rating 3 とカテゴリ "Motel" を選択した後、前のファセットクエリ結果を絞り込みます。

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

ファセット検索で、クエリで返される一意の語句に上限を設定します。既定値は 10 ですが、ファセット属性でカウントパラメーターを使用することで、この値を増減できます。この例では、5 に制限された、都市のファセットを返します。
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

特定のフィールド (たとえば、言語フィールド) 内のインデックスを検索します。

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

複数のフィールドにまたがるインデックスを検索します。たとえば、複数の言語の検索可能なフィールドをすべて同じインデックスに格納してクエリできます。英語とフランス語の説明が同じドキュメントに共存している場合は、クエリ結果の一部またはすべてを返すことができます。
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
一度にクエリを実行できるのはインデックスのみです。一度に 1 つずつクエリを実行する予定がない限り、言語ごとに複数のインデックスを作成しないでください。

ページング - アイテムの最初のページを取得します (ページサイズは 10)。

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

ページング - アイテムの 2 ページ目を取得します (ページサイズは 10)。

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

特定のフィールドのセットを取得します。

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

特定のフィルター式に一致するドキュメントを取得します。

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

インデックスを検索し、ヒットハイライトでフラグメントを返します。

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

インデックスを検索し、参照場所に近いものから順番に並べられたドキュメントを返します。

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

"geo" というスコアリングプロファイルがあり、2 つの距離スコアリング関数があり、もう 1 つは "currentLocation" というパラメーターを定義し、もう 1 つは "lastLocation" というパラメーターを定義している場合にインデックスを検索します。次の例では、"currentLocation" には 1 つのダッシュ (-) の区切り記号があります。その後に経度と緯度の座標が続きます。経度は負の値です。
```
GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
簡単なクエリ構文を使用して、インデックス内のドキュメントを検索します。このクエリは、検索可能なフィールドに語句 "comfort" および "location" が含まれていて "motel" が含まれないホテルを返します。
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
ヒント

searchMode=all を使用すると、既定の searchMode=any がオーバーライドされ、-motel が「OR NOT」ではなく「AND NOT」を意味します。 searchMode=allを指定しないと、検索結果を制限するのではなく拡大する "OR NOT" になり、一部のユーザーにとっては直感に反している可能性があります。
Lucene クエリ構文を使用して、インデックス内のドキュメントを検索します)。このクエリは、カテゴリフィールドに "budget" (低料金) が含まれ、すべての検索可能なフィールドに "recently renovated" (最近改修済み) というフレーズが含まれるホテルを返します。 "recently renovated" というフレーズを含むドキュメントは、用語のブースト値 (3) の結果、高いランクになります。
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
より短い待機時間で一貫したスコアリングを優先しながら、インデックス内のドキュメントを検索します。このクエリは、インデックス全体のドキュメント頻度を計算し、同じ "セッション" 内のすべてのクエリに対して同じレプリカをターゲットにすることをベストエフォートで行います。これにより、安定した再現可能なランク付けが生成されます。
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```

ドキュメントの検索 (Azure AI Search REST API)

URI パラメーター

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

要求ヘッダー

要求本文

クエリパラメーター

Response

例

こちらもご覧ください

その他のリソース

ドキュメントの検索 (Azure AI Search REST API)

URI パラメーター

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

要求ヘッダー

要求本文

クエリ パラメーター

Response

例

こちらもご覧ください

その他のリソース

クエリパラメーター