Query API は、検索インターフェースを作成したり、アプリケーションに検索結果を埋め込んだりする search メソッドと suggest メソッド提供します。
最小要件のウェブ アプリケーションでは、検索ウィジェットの使用を検討してください。検索ウィジェットを使用して検索インターフェースを作成するをご覧ください。
検索インターフェースを作成する
最小限の検索インターフェースを作成するには、いくつかの手順が必要です。
- 検索アプリケーションを構成します。
- アプリケーションの OAuth 認証情報を生成します。
- インデックスをクエリします。
- クエリ結果を表示します。
ページング、並べ替え、フィルタリング、ファセット、自動入力などの機能を使用して、インターフェースを強化できます。
検索アプリケーションを構成する
検索インターフェースごとに、少なくとも 1 つの検索アプリケーションを作成する必要があります。検索アプリケーションには、データソース、並べ替え順序、フィルタ、ファセットなどのデフォルト パラメータが用意されています。これらのパラメータは、Query API を使用してオーバーライドできます。
クエリで使用されるデータソースの数を、検索アプリケーションで構成された数より多くすることはできません。dataSourceRestrictions を使用すると、クエリをこれらのソースのサブセットに制限できます。
詳細については、検索エクスペリエンスをカスタマイズするをご覧ください。
アプリケーションの OAuth 認証情報を生成する
Cloud Search API へのアクセスを構成するの手順に加えて、ウェブ アプリケーションの OAuth 認証情報も生成する必要があります。
認証情報を使用してユーザーの代わりに承認をリクエストします。スコープ https://www.googleapis.com/auth/cloud_search.query を使用します。
OAuth オプションの詳細については、Google Identity Platform をご覧ください。
インデックスをクエリする
search メソッドを使用してインデックスを検索します。
すべてのリクエストにテキスト query と searchApplicationId を含める必要があります。
この例では、映画データソースをクエリします。
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
}
}
クエリ結果を表示する
検索インターフェースは、アイテム title と元のアイテムへのリンクを表示する必要があります。スニペットとメタデータを使用して、表示を改善することもできます。
補足結果を処理する
クエリに一致する結果が十分でない場合、Cloud Search は補足結果を返します。これは、queryInterpretation フィールドで示されます。補足結果のみが返された場合、InterpretationType は REPLACE になります。ブレンドされている場合は BLEND です。
補足結果を返す場合は、ユーザーに通知することを検討してください。REPLACE の場合は、「検索条件に一致する結果はありませんでした。類似のクエリの結果を表示しています。」
人物の検索結果を処理する
Cloud Search は、人物検索機能を使用して、人物と社員情報に関連するドキュメントを返します。結果は structuredResults フィールドにあります。
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
直属の部下の一致
[直属の部下の一致] を使用すると、ユーザーは特定の人物の直属の部下を確認できます。レスポンスには、cardType が RELATED_PEOPLE_ANSWER_CARD の assistCardProtoHolder が含まれます。
最適化をオフにする
補足結果などの最適化はデフォルトで有効になっています。無効にするには:
- 検索アプリケーション レベル:
force_verbatim_modeをtrueに設定します。 - クエリレベル:
enableVerbatimModeをtrueに設定します。
スニペットをハイライト表示する
Cloud Search は、インデックス登録されたテキストまたは HTML のスニペットを返します。クエリ用語が存在する場合、matchRanges はその場所を特定します。これらの範囲を使用してテキストをハイライト表示します。
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...
メタデータを表示する
createTime、updateTime、構造化データなどの情報には、metadata フィールドを使用します。displayOptions を使用して構造化データを表示します。
追加の結果を取得する
結果をさらに取得するには、start フィールドを選択したオフセットに設定します。pageSize でページサイズを調整します。resultCount を使用して、アイテムの合計数または推定数を表示します。
検索結果の並べ替え
sortOptions を使用して順序を指定します。
operatorName: 並べ替えの基準となるプロパティ。sortOrder:ASCENDINGまたはDESCENDING。
関連性は、デフォルトのセカンダリ ソートキーです。
フィルタの追加
検索アプリケーションまたはリクエストのフィルタを使用して結果を制限します。両方でソースのフィルタを指定している場合は、両方が true と評価される必要があります。
dataSourceRestrictions.filterOptions[] でフィルタを適用します。主なフィルタの種類:
- オブジェクト フィルタ: 一致を特定のタイプに制限します。
- 値フィルタ: 演算子と値に基づいて一致を制限します。
複合フィルタは、複数の値フィルタを組み合わせます。
結果をファセットで絞り込む
ファセットを使用すると、ユーザーがクエリをインタラクティブに絞り込むことができます。ファセットをリクエストすると、Cloud Search はそれらのプロパティの最も頻繁に出現する値を計算します。
一般的なパターン: 1. ファセット プロパティを指定するクエリ。1. 検索とファセットの結果をレンダリングします。1. ユーザーがファセット値を選択します。1. 選択に基づいてフィルタを使用してクエリを繰り返します。
整数ベースのフィールドを含むファセット結果
整数プロパティをファセット可能としてマークすると、範囲で結果を絞り込むことができます（例:100 ～ 200 ページ）。isFacetable を true に設定し、スキーマでデフォルトのバケット オプションを定義します。
ドキュメントのサイズまたは日付でファセット結果を取得する
予約済み演算子を使用します。
itemsize: ファイルサイズ（バイト単位）。createddatetimestamp: 作成日。lastmodified: 変更日。
候補を追加する
クエリ履歴、連絡先、ドキュメント コンテンツに基づく自動補完には、suggest API を使用します。