Query API は、検索インターフェースを作成したり、アプリケーションに検索結果を埋め込んだりする search メソッドと suggest メソッド提供します。
最小要件のウェブ アプリケーションの場合は、検索ウィジェットの使用を検討してください。 詳細については、次をご覧ください: 検索ウィジェットで検索インターフェースを作成する
検索インターフェースを作成する
最小限の検索インターフェースを構築するには、いくつかの手順が必要です。
- 検索アプリケーションを構成する
- アプリケーションの OAuth 認証情報を生成する
- インデックスを照会する
- クエリ結果を表示する
ページング、並べ替え、フィルタリング、ファセット、自動提案などの機能を使用して、検索インターフェースをさらに強化できます。
検索アプリケーションを構成する
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 という 2 つの情報を含める必要があります。
照合用のアイテムとその ID を識別する searchApplicationId が
使用する検索アプリケーション。
次のスニペットは、映画タイタニックの映画データソースへのクエリを示しています。
{
"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 の場合は、「Your search for your
元のクエリと一致する結果が十分ではありませんでした。類似の検索結果を表示しています
表示されます。
ユーザーの検索結果を処理する
Cloud Search は、2 種類の「人物の検索結果」を返します。1 つは特定のエンティティに関連するドキュメント、
クエリで使用されている名前の人物と、人物の従業員情報。
その名前をクエリで使用します後者のタイプの結果は、Cloud Functions の関数です。
Google 検索のユーザー検索機能と、そのようなクエリの結果は次の場所で確認できます:
structuredResults
フィールドで確認できます。
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
ダイレクト レポートの照合
ダイレクト レポート マッチングは Cloud Search のユーザー検索機能で、
組織内のユーザーの直属の部下を表示できます。
結果は structuredResults フィールドで確認できます。
ユーザーのマネージャーや直属の部下に関するクエリの場合、レスポンスには
structuredResults 内の assistCardProtoHolder。「
assistCardProtoHolder には cardType というフィールドがあり、これは次と等しくなります。
RELATED_PEOPLE_ANSWER_CARD。assistCardProtoHolder にはカードが含まれています。
実際のレスポンスを含む relatedPeopleAnswerCard です。
これには、subject（クエリに含まれる人物）と、
relatedPeople は、被写体に関連する人物のセットです。「
relationType フィールドは、値 MANAGER または DIRECT_REPORTS を返します。
次のコードは、次に一致する直属の部下に対するレスポンスの例を示しています。 query:
{
"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 の例では、スニペットを
一致する各範囲を <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"
}
}
}
]
}
]
}
}
}
]
}
]
}
結果をファセットで絞り込む
ファセットは、検索結果を絞り込むためのカテゴリを表すインデックス登録済みプロパティです。ファセットを使用すると、ユーザーがクエリをインタラクティブに絞り込み、関連するアイテムをすばやく見つけるのに役立ちます。
Facets は 検索アプリケーション。 クエリの設定でオーバーライドできます
ファセットのリクエスト時に、Cloud Search は、一致するアイテムの中でリクエストされたプロパティの頻度が高い値を計算します。これらの値はレスポンスで返されます。これらの値を使用して、後続のクエリで結果を絞り込むフィルタを作成します。
ファセットの一般的な操作パターンは、次のとおりです。
- ファセット結果に含めるプロパティを指定する初期クエリを作成します。
- 検索とファセットの結果をレンダリングします。
- ユーザーは、結果を絞り込む 1 つ以上のファセット値を選択します。
- 選択された値に基づいてフィルタを使用してクエリを繰り返します。
たとえば、年と 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 は
検索アプリケーションにもクエリ リクエストにもファセットがない場合のスキーマ
定義します。クエリで定義されたファセットは、定義されたファセットよりも優先されます。
ファセットが定義され、検索アプリケーションに定義されたファセットが
スキーマで定義されたファセットよりも優先される。
ドキュメントのサイズまたは日付によるファセット結果
次を使用:
予約済み演算子
ドキュメントのファイルサイズ（バイト単位）または
ドキュメントが作成または変更されたとき。カスタムスキーマを定義する必要はなく
検索アプリケーションの operatorName 値で
FacetOptions。
- ドキュメント サイズによるファセットの場合は、
itemsizeを使用してバケット化オプションを定義します。 - ドキュメントの作成日によるファセットには、
createddatetimestampを使用します。 - ドキュメントの更新日によるファセットには、
lastmodifiedを使用します。
ファセット バケットの解釈
facetResults
プロパティにユーザーの正確なフィルタ リクエストが含まれる
各フィールドの filter フィールドに
bucket。
整数ベースでないファセットの場合、facetResults には次のエントリが含まれます。
リクエストする各プロパティを記録します。各プロパティについて、呼び出しと呼ばれる値または範囲のリストが
buckets が指定されています。頻度の高い値が先に表示されます。
ユーザーがフィルタリングする値を 1 つ以上選択すると、選択したフィルタで新しいクエリが作成され、API に再度クエリが実行されます。
候補を追加する
suggest API を使用して、ユーザーの個人的なクエリ履歴およびコンタクトとそのドキュメント コーパスに基づいてクエリの自動補完を提供します。
たとえば、次の呼び出しでは、部分的な語句 jo の候補が示されます。
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
結果として得られた候補をアプリケーションに合わせて表示できます。