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
と、使用する検索アプリケーションの 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 種類の「ユーザー結果」が返されます。1 つは、クエリで名前が使われている人に関連するドキュメントで、もう 1 つは、クエリで名前が使用されている人の従業員情報です。後者の種類の結果は、Cloud Search のユーザー検索機能の関数であり、このようなクエリの結果は、クエリ API レスポンスの structuredResults
フィールドにあります。
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
直接レポートの一致
直接レポート マッチングは Cloud Search のユーザー検索機能であり、ユーザーは組織内の個人の直属の部下を表示できます。結果は structuredResults
フィールド内で取得できます。
個人のマネージャーや直属の部下に関するクエリの場合、レスポンスの structuredResults
内に assistCardProtoHolder
が含まれます。assistCardProtoHolder
には RELATED_PEOPLE_ANSWER_CARD
と等しい cardType
というフィールドがあります。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 つ以上のファセット値を選択します。
- 選択された値に基づいてフィルタを使用してクエリを繰り返します。
たとえば、年と 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"
}
}
結果として得られた候補をアプリケーションに合わせて表示できます。