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...
表示メタデータ
metadata
フィールドを使用して、createTime、updateTime、構造化データなどの情報を取得します。
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 を使用して、クエリ履歴、連絡先、ドキュメント コンテンツに基づいて自動補完を行います。