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

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

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

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

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

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

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

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

1 つ以上の検索アプリケーションを作成して、作成する各検索インターフェースに関連付ける必要があります。検索アプリケーションは、使用するデータソース、並べ替え順、フィルタ、ファセットなど、クエリのデフォルト パラメータを提供します。必要に応じて、クエリ 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": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

最適化（補足結果を含む）をオフにする

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

• 補足結果、類義語、スペル修正など、検索アプリケーション レベルですべての最適化を無効にするには、検索アプリケーションで QueryInterpretationConfig.force_verbatim_mode を true に設定します。

• 補完結果、類義語、スペル修正など、検索クエリレベルですべての最適化を無効にするには、検索クエリで QueryInterpretationOptions.enableVerbatimMode を true に設定します。

• 検索アプリケーション レベルで補助結果を無効にするには、検索クエリで QueryInterpretationOptions.forceDisableSupplementalResults を true に設定します。

• 検索クエリレベルで補助結果を無効にするには、検索クエリで QueryInterpretationOptions.disableSupplementalResults を true に設定します。

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

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

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

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

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 のセットが含まれます。各メタラインは、スキーマで構成された表示ラベルと値のペアの配列です。

追加の結果を取得する

追加の結果を取得するには、リクエストの 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"
  }
}

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