Query API を使用して検索インターフェースを作成する

Query API は、検索インターフェースを作成したり、アプリケーションに検索結果を埋め込んだりする search メソッドと suggest メソッド提供します。

最小要件のウェブ アプリケーションでは、検索ウィジェットの使用を検討してください。詳細については、検索ウィジェットを使用して検索インターフェースを作成するをご覧ください。

検索インターフェースを作成する

最小限の検索インターフェースを作成するには、いくつかの手順が必要です。

  1. 検索アプリケーションを構成する
  2. アプリケーションの OAuth 認証情報を生成する
  3. インデックスを照会する
  4. クエリ結果を表示する

ページング、並べ替え、フィルタリング、ファセット、自動提案などの機能を使用して、検索インターフェースをさらに強化できます。

検索アプリケーションを構成する

1 つ以上の検索アプリケーションを作成して、作成する各検索インターフェースに関連付ける必要があります。検索アプリケーションには、クエリ用のデフォルト パラメータ（使用するデータソース、並べ替え順序、フィルタ、リクエストするファセットなど）が用意されています。必要に応じて、Query API を使用してこれらのパラメータをオーバーライドできます。

検索アプリケーションの詳細については、Cloud Search の検索機能をカスタマイズするをご覧ください。

アプリケーションの OAuth 認証情報を生成する

Google Cloud Search API へのアクセスを構成するの手順に加えて、ウェブ アプリケーションの OAuth 認証情報も生成する必要があります。作成する認証情報の種類は、API が使用されるコンテキストによって異なります。

認証情報を使用してユーザーの代わりに承認をリクエストします。承認をリクエストする場合は、スコープ https://www.googleapis.com/auth/cloud_search.query を使用します。

OAuth オプションとクライアント ライブラリの詳細については、[Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"} をご覧ください。

インデックスをクエリする

インデックスに対して検索を行うには、search メソッドを使用します。

各リクエストに、アイテムと照合するテキスト query と、使用する検索アプリケーションの ID を指定する searchApplicationId の 2 つの情報が含まれている必要があります。

次のスニペットは、映画タイタニックの映画データソースへのクエリを示しています。

{   "query": "titanic",   "requestOptions": {     "searchApplicationId": "searchapplications/<search_app_id>"   }, }

クエリ結果を表示する

検索インターフェースは、少なくともアイテム title と元のアイテムへのリンクを表示する必要があります。スニペットやメタデータなど、検索結果に存在する追加情報を活用することで、検索結果の表示をさらに向上させることができます。

補足結果を処理する

デフォルトでは、ユーザーのクエリに対する結果が十分でない場合、Cloud Search は補足結果を返します。レスポンスの queryInterpretation フィールドは、補足結果が返されるタイミングを示します。補足結果のみが返された場合、InterpretationType は REPLACE に設定されます。元のクエリの結果が補足結果とともにいくつか返された場合、InterpretationType は BLEND に設定されます。いずれの場合も QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY。

補足結果が返された場合は、補足結果が返されたことを示すテキストを提供することを検討してください。たとえば、REPLACE の場合は、「元のクエリの検索結果はありませんでした。類似のクエリの結果を表示しています。」

BLEND の場合は、「元のクエリの検索結果が十分に一致しませんでした。類似するクエリの検索結果も表示しています。」

人物の検索結果を処理する

Cloud Search は、クエリで使用された名前の人物に関連するドキュメントと、クエリで使用された名前の人物の社員情報という 2 種類の「人物の結果」を返します。後者のタイプの結果は、Cloud Search の人物検索機能の関数です。このようなクエリの結果は、クエリ API レスポンスの structuredResults フィールドにあります。

{   "results": [...],   "structuredResults": [{     "person": {...}   }] }

直属の部下の照合

「直属の部下の一致」は、Cloud Search のユーザー検索機能です。組織内のユーザーの直属の部下を確認できます。結果は structuredResults フィールドで確認できます。

ユーザーのマネージャーまたは直属の部下に関するクエリの場合、レスポンスには structuredResults 内に assistCardProtoHolder が含まれます。assistCardProtoHolder には cardType というフィールドがあり、これは RELATED_PEOPLE_ANSWER_CARD と同じになります。assistCardProtoHolder には、実際のレスポンスを含む relatedPeopleAnswerCard というカードが含まれています。これには、subject（クエリに含まれていた人物）と、主題に関連する人物のセットである relatedPeople が含まれます。relationType フィールドは、値 MANAGER または DIRECT_REPORTS を返します。

次のコードは、直属の部下の一致クエリに対するレスポンスの例を示しています。

{   "results": [],   "structuredResults": [{     "assistCardProtoHolder": {       "extensions": {         "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",         "cardMetadata": {           "cardCategory": "ANSWER"         },         "cardType": "RELATED_PEOPLE_ANSWER_CARD",         "relatedPeopleAnswerCard": {           "subject": {             "email": "[email protected]",             "displayName": "Adam Stanford"             "manager": {               "email": "[email protected]"             }           },           "relatedPeople": [{             "email": "[email protected]",             "displayName": "Edgar Mountain Ramirez"           }, {             "email": "[email protected]",             "displayName": "Francisco Jose Martinez"           }],           "relationType": "DIRECT_REPORTS",         }       }     }   }] }

補助結果を含む最適化をオフにする

デフォルトでは、補足結果などの最適化が有効になっています。ただし、検索アプリケーションとクエリの両方のレベルで、すべての最適化または補足結果のみをオフにすることはできます。

スニペットをハイライト表示する

インデックス登録されているテキストや HTML コンテンツを含むアイテムが返される場合、コンテンツのスニペットが返されます。このコンテンツは、返されたアイテムの関連性を判断するのに役立ちます。

クエリの単語がスニペットに存在する場合、単語の場所を特定する 1 つ以上の一致範囲も返されます。

結果をレンダリングするときに一致するテキストをハイライト表示するには、matchRanges を使用します。次の javascript の例では、スニペットが、一致する各範囲が <span> タグでラップされた HTML マークアップに変換されます。

function highlightSnippet(snippet) {   let text = snippet.snippet;   let formattedText = text;   if (snippet.matchRanges) {     let parts = [];     let index = 0;     for (let match of snippet.matchRanges) {       let start = match.start || 0; // Default to 0 if omitted       let end = match.end;       if (index < start) { // Include any leading text before/between ranges         parts.push(text.slice(index, start));       }       parts.push('<span class="highlight">');       parts.push(text.slice(start, end));       parts.push('</span>');       index = end;     }     parts.push(text.slice(index)); // Include any trailing text after last range     formattedText = parts.join('');   }   return formattedText; }

スニペットを指定します。

{   "snippet": "This is an example snippet...",   "matchRanges": [     {       "start": 11,       "end": 18     }   ] }

結果の HTML 文字列は次のようになります。

This is an <span class="highlight">example</span> snippet...

メタデータを表示する

metadata 項目を使用して、ユーザーに関連する可能性がある、返されるアイテムに関する追加情報を表示します。metadata フィールドには、アイテムの createTime と updateTime、およびアイテムに関連付けられた、返すことができる構造化データが含まれます。

構造化データを表示するには、displayOptions 項目を使用します。displayOptions フィールドには、オブジェクト タイプの表示ラベルと一連の metalines が含まれます。各 metaline は、スキーマで構成された表示ラベルと値のペアの配列です。

追加の結果を取得する

追加の結果を取得するには、目的のオフセットへのリクエストに start 項目を設定します。各ページのサイズは pageSize 項目で調整できます。

返されたアイテムの数、または返されたアイテムをページ分けするページング コントロールを表示するには、resultCount 項目を使用します。結果セットのサイズに応じて、実際の値か推定値が提供されます。

検索結果の並べ替え

返されるアイテムの順序を指定するには、sortOptions 項目を使用します。sortOptions 値は、次の 2 つの項目を持つオブジェクトです。

  • operatorName - 並べ替える構造化データ プロパティの演算子。複数の演算子を持つプロパティの場合、並べ替えは、メインの等価演算子でのみ行うことができます。
  • sortOrder - 並べ替える方向。ASCENDING または DESCENDING。

関連性はセカンダリ ソートキーとしても使用されます。クエリで並べ替え順が指定されていない場合、結果は関連性のみによってランク付けされます。

"sortOptions": {   "operatorName": "priority",   "sortOrder": "DESCENDING" }

フィルタの追加

クエリ式に加えてフィルタを適用することで、さらに結果を制限できます。フィルタは、検索アプリケーションと検索リクエストの両方で指定できます。

リクエストまたは検索アプリケーションにフィルタを追加するには、dataSourceRestrictions.filterOptions[] 項目にフィルタを追加します。

データソースをさらにフィルタリングするには、主に 2 つの方法があります。

  • filterOptions[].objectType プロパティを使用したオブジェクト フィルタ - 一致するアイテムをカスタム スキーマで定義された指定のタイプに制限します。
  • 値フィルタ - クエリ演算子と指定された値によって、一致するアイテムを制限します。

複合フィルタを使用すると、複数の値フィルタを論理式に組み合わせてより複雑なクエリを作成できます。

ムービー スキーマの例では、現在のユーザーに基づいて年齢制限を適用し、MPAA 評価に基づいて利用可能な映画を制限できます。

{   "query": "adventure",   "requestOptions": {     "searchApplicationId": "<search_app_id>"   },   "dataSourceRestrictions": [     {       "source": {         "name": "datasources/<data_source_id>"       },       "filterOptions": [         {           "objectType": "movie",           "filter": {             "compositeFilter": {               "logicOperator": "AND"               "subFilters": [                 {                   "compositeFilter": {                   "logicOperator": "OR"                   "subFilters": [                     {                       "valueFilter": {                         "operatorName": "rated",                         "value": {                           "stringValue": "G"                         }                       }                     },                     {                       "valueFilter": {                         "operatorName": "rated",                         "value": {                           "stringValue": "PG"                         }                       }                     }                   ]                 }               ]             }           }         }       ]     }   ] }

結果をファセットで絞り込む

ファセットは、検索結果を絞り込むためのカテゴリを表すインデックス登録済みプロパティです。ファセットを使用すると、ユーザーがクエリをインタラクティブに絞り込み、関連するアイテムをすばやく見つけるのに役立ちます。

ファセットは検索アプリケーションで定義できます。また、クエリの設定でオーバーライドできます。

ファセットのリクエスト時に、Cloud Search は、一致するアイテムの中でリクエストされたプロパティの頻度が高い値を計算します。これらの値はレスポンスで返されます。これらの値を使用して、後続のクエリで結果を絞り込むフィルタを作成します。

ファセットの一般的な操作パターンは、次のとおりです。

  1. ファセット結果に含めるプロパティを指定する初期クエリを作成します。
  2. 検索とファセットの結果をレンダリングします。
  3. ユーザーは、結果を絞り込む 1 つ以上のファセット値を選択します。
  4. 選択された値に基づいてフィルタを使用してクエリを繰り返します。

たとえば、年齢と MPAA 評価による映画クエリの絞り込みを有効にするには、クエリに facetOptions プロパティを含めます。

"facetOptions": [   {     "sourceName": "datasources/<data_source_id>",     "operatorName": "year"   },   {     "sourceName": "datasources/<data_source_id>",     "operatorName": "rated"   } ]

整数ベースのフィールドを含むファセット結果

整数ベースのフィールドでリクエスト結果をファセットすることもできます。たとえば、book_pages という整数プロパティをファセット可能としてマークして、「100 ～ 200」ページの書籍の検索結果を絞り込むことができます。

整数プロパティ フィールドのスキーマを設定する際は、isFacetable を true に設定し、対応するバケット オプションを integerPropertyOptions に追加します。これにより、すべての整数ファセット可能なプロパティにデフォルトのバケット オプションが定義されます。

バケット オプションのロジックを定義するときに、範囲を示す増分値の配列を指定します。たとえば、エンドユーザーが範囲を 2, 5, 10, 100 として指定した場合、<2、[2-5)、[5-10)、[10-100)、>=100 のファセットが計算されます。

リクエストの facetOptions に同じバケット オプションを定義することで、整数ベースのファセットをオーバーライドできます。必要に応じて、検索アプリケーションとクエリ リクエストの両方にファセット オプションが定義されていない場合、Cloud Search はスキーマで定義されたバケット オプションを使用します。クエリで定義されたファセットは、検索アプリケーションで定義されたファセットよりも優先されます。また、検索アプリケーションで定義されたファセットは、スキーマで定義されたファセットよりも優先されます。

ドキュメントのサイズまたは日付でファセット結果を取得する

予約済み演算子を使用すると、ドキュメントのファイルサイズ（バイト単位）、ドキュメントの作成日または変更日で検索結果を絞り込むことができます。カスタム スキーマを定義する必要はありませんが、検索アプリケーションの FacetOptions で operatorName 値を指定する必要があります。

  • ドキュメント サイズでファセット処理を行うには、itemsize を使用してバケット オプションを定義します。
  • ドキュメントの作成日でファセット処理するには、createddatetimestamp を使用します。
  • ドキュメントの変更日でファセット処理を行うには、lastmodified を使用します。

ファセット バケットの解釈

検索クエリ レスポンスの facetResults プロパティには、各 bucket の filter フィールドにユーザーの正確なフィルタ リクエストが含まれます。

整数に基づかないファセットの場合、facetResults にはリクエストされた各プロパティのエントリが含まれます。プロパティごとに、buckets と呼ばれる値または範囲のリストが提供されます。頻度の高い値が先に表示されます。

ユーザーがフィルタリングする値を 1 つ以上選択すると、選択したフィルタで新しいクエリが作成され、API に再度クエリが実行されます。

候補を追加する

suggest API を使用して、ユーザーの個人的なクエリ履歴およびコンタクトとそのドキュメント コーパスに基づいてクエリの自動補完を提供します。

たとえば、次の呼び出しでは、部分的な語句 jo の候補が示されます。

{   "query": "jo",   "requestOptions": {     "searchApplicationId": "<search_app_id>",     "peoplePhotoOptions": {       "peoplePhotoUrlSizeInPx": 32     },     "timeZone": "America/Denver"   } }

結果として得られた候補をアプリケーションに合わせて表示できます。