- HTTP リクエスト
- リクエストの本文
- レスポンスの本文
- 承認スコープ
- QueryTranslateationOptions
- クエリ解釈
- QueryTranslateation.TranslateationType
- QueryTranslateation.Reason
- SearchResult
- スニペット
- MatchRange
- メタデータ
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- 試してみる
Cloud Search Query API には、ユーザーのクエリから最も関連性の高い結果を返す検索メソッドが用意されています。検索結果は Gmail や Google ドライブなどの Google Workspace アプリから取得されるものもあれば、サードパーティがインデックス登録したデータから取得されるものもあります。
注: この API を実行するには、標準のエンドユーザー アカウントが必要です。サービス アカウントで Query API リクエストを直接実行することはできません。サービス アカウントを使用してクエリを実行するには、Google Workspace ドメイン全体の権限の委任を設定します。
HTTP リクエスト
POST https://cloudsearch.googleapis.com/v1/query/search
この URL は gRPC Transcoding 構文を使用します。
リクエスト本文
リクエストの本文には、次の構造のデータが含まれます。
JSON 表現 |
---|
{ "requestOptions": { object ( |
フィールド | |
---|---|
requestOptions |
リクエスト オプション(検索アプリケーションとユーザーのタイムゾーンなど)。 |
query |
クエリ文字列。演算子を使用して検索を絞り込むで、サポートされている検索演算子を確認する |
pageSize |
1 ページに対して返される検索結果の最大数。有効な値は 1 ~ 100 です。デフォルト値は 10 です。2,000 件を超える結果がリクエストされた場合、最小値は 50 です。 |
start |
結果の開始インデックス。 |
dataSourceRestrictions[] |
クエリに使用するソース。指定しない場合、現在の検索アプリケーションのデータソースがすべて使用されます。 |
facetOptions[] |
|
sortOptions |
検索結果を並べ替えるためのオプション |
queryInterpretationOptions |
ユーザーのクエリを解釈するためのオプションです。 |
contextAttributes[] |
リクエストのコンテキスト属性。検索結果のランキングを調整するために使用されます。要素の最大数は 10 です。 |
レスポンスの本文
成功すると、レスポンスの本文に次の構造のデータが含まれます。
Search API レスポンス。
JSON 表現 |
---|
{ "queryInterpretation": { object ( |
フィールド | |
---|---|
queryInterpretation |
ユーザークエリのクエリの解釈結果。クエリの解釈が無効になっている場合は空になります。 |
results[] |
検索クエリの結果。 |
structuredResults[] |
ユーザークエリの構造化された結果。これらの結果は pageSize にはカウントされません。 |
spellResults[] |
クエリのスペル表記。 |
facetResults[] |
ファセットの結果が繰り返されます。 |
hasMoreResults |
クエリに一致する検索結果があるかどうか。 |
debugInfo |
レスポンスに関するデバッグ情報。 |
errorInfo |
レスポンスのエラー情報。 |
resultCounts |
結果の数情報を拡張しました。 |
共用体フィールド
まれなケースですが、システムですべてのドキュメントを検索できない場合は、クエリを再実行してください。 |
|
resultCountEstimate |
このクエリの推定結果数。 |
resultCountExact |
このクエリの正確な結果数。 |
認証スコープ
次の OAuth スコープのいずれかが必要です。
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
詳しくは、OAuth 2.0 の概要をご覧ください。
クエリ解釈オプション
ユーザーのクエリを解釈するためのオプションです。
JSON 表現 |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
フィールド | |
---|---|
disableNlInterpretation |
クエリの自然言語(NL)解釈を無効にするフラグ。デフォルトは false です。自然言語による通訳を無効にするには、true に設定します。NL の解釈は、定義済みのデータソースにのみ適用されます。 |
enableVerbatimMode |
自然言語(NL)によるクエリの解釈、補足結果の取得、類義語の使用(カスタム キーワードを含む)など、すべての内部最適化を無効にするには、このフラグを有効にします。N1 解釈は、2 つのフラグのいずれかが true の場合に無効になります。 |
disableSupplementalResults |
このフラグを使用して、クエリの補足結果を無効にします。SearchApplication レベルで選択された補助結果設定は、True に設定されている場合より優先されます。 |
クエリ解釈
JSON 表現 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
フィールド | |
---|---|
interpretedQuery |
検索で使用されているクエリの解釈。たとえば、自然言語による意図がある「john from email」は、「from:john source:mail"」のように解釈されます。理由が NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY の場合、このフィールドは入力されません。 |
interpretationType |
|
reason |
クエリの解釈の理由。解釈タイプが NONE でない場合、このフィールドは指定されません。 |
QueryTranslateation.TranslateationType
列挙型 | |
---|---|
NONE |
検索結果の取得には、自然言語解釈や広義のクエリは使用されません。 |
BLEND |
元のクエリの結果は他の結果と統合されます。他のクエリの結果を元のクエリの結果と統合する理由は、下の [理由] 欄に入力されます。 |
REPLACE |
元のクエリの結果は置き換えられます。元のクエリの結果を置換する理由は、下の [&33;理由'] フィールドに入力されます。 |
QueryTranslateation.Reason
列挙型 | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
自然言語によるクエリの解釈を使用して、検索結果を取得します。 |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
クエリとドキュメントの用語の類似性は、ユーザーの選択に対して十分な検索結果が見つからなかったため、クエリを選択的に範囲を広げて、追加の検索結果を取得するために使用されます。このケースでは、解釈されたクエリは空になります。 |
検索結果
ドキュメントのインデックス付き情報を含む結果。
JSON 表現 |
---|
{ "title": string, "url": string, "snippet": { object ( |
フィールド | |
---|---|
title |
検索結果のタイトル。 |
url |
検索結果の URL。URL に、実際のアイテムへの Google リダイレクトが含まれています。この URL は署名されており、変更できません。 |
snippet |
この結果で利用可能なすべてのスニペット(サマリー)を連結したものです。 |
metadata |
検索結果のメタデータ。 |
clusteredResults[] |
ソースがクラスタ化されている場合は、クラスタ化された結果のリストを提供します。クラスタ化された結果のレベルは 1 つだけです。現在のソースでクラスタリングが有効になっていない場合、このフィールドは空になります。 |
debugInfo |
この検索結果に関する情報のデバッグ。 |
snippet
検索結果のページのコンテンツの要約。
JSON 表現 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
フィールド | |
---|---|
snippet |
ドキュメントのスニペット。ドキュメントのスニペット。エスケープする前に HTML 文字をエスケープする必要があります。 |
matchRanges[] |
スニペット内の一致した範囲です。 |
マッチ範囲
スニペットの一致した範囲 [start, end)。
JSON 表現 |
---|
{ "start": integer, "end": integer } |
フィールド | |
---|---|
start |
スニペット内の一致の最初の位置です。 |
end |
スニペットで対戦を終了します。 |
Metadata
一致した検索結果のメタデータ。
JSON 表現 |
---|
{ "source": { object ( |
フィールド | |
---|---|
source |
結果の名前付きソース(Gmail など)。 |
mimeType |
検索結果の MIME タイプ。 |
thumbnailUrl |
検索結果のサムネイル URL。 |
owner |
検索結果のドキュメントまたはオブジェクトのオーナー(通常は作成者)。 |
createTime |
検索結果でのこのドキュメントまたはオブジェクトの作成時間。 RFC3339 UTC & Zulu 形式のタイムスタンプ(解像度はナノ秒、小数点以下 9 桁まで)。(例: |
updateTime |
検索結果のオブジェクトの最終更新日。アイテム内で設定されていない場合、ここで返される値は空です。 RFC3339 UTC & Zulu 形式のタイムスタンプ(解像度はナノ秒、小数点以下 9 桁まで)。(例: |
fields[] |
構造化データ内のインデックス付きフィールド。汎用的な名前付きプロパティとして返されます。 |
displayOptions |
構造化データの検索結果の表示方法を指定するオプション |
objectType |
検索結果のオブジェクト タイプ。 |
ResultDisplayMetadata
JSON 表現 |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
フィールド | |
---|---|
objectTypeLabel |
オブジェクトの表示ラベル。 |
metalines[] |
結果とともに表示されるメタライン コンテンツ。 |
ResultDisplayMetadata.ResultDisplayLine
表示される線を構成するフィールドのコレクション
JSON 表現 |
---|
{
"fields": [
{
object ( |
フィールド | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
query.search 結果のフィールドを表示する
JSON 表現 |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
フィールド | |
---|---|
label |
宿泊施設の表示ラベル。 |
operatorName |
宿泊施設の演算子名。 |
property |
宿泊施設の名前と値のペア。 |
結果デバッグ情報
結果に関する情報のデバッグ。
JSON 表現 |
---|
{ "formattedDebugInfo": string } |
フィールド | |
---|---|
formattedDebugInfo |
表示用の一般的なデバッグ情報。 |
StructuredResult
検索リクエストの一部として返される構造化された結果。
JSON 表現 |
---|
{
"person": {
object ( |
フィールド | |
---|---|
person |
人物 |
SpellResult(スペル結果)
JSON 表現 |
---|
{ "suggestedQuery": string } |
フィールド | |
---|---|
suggestedQuery |
クエリの候補のスペル。 |
FacetResult
ソース固有のファセット レスポンス
JSON 表現 |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
フィールド | |
---|---|
sourceName |
ファセット結果が返されるソース名。空白になりません。 |
objectType |
ファセット結果が返されるオブジェクト型。これは空でもかまいません。 |
operatorName |
ファセットに選択した演算子の名前。@see cloudsearch.SchemaPropertyOptions |
buckets[] |
少なくとも 1 つの結果とそれに対応するフィルタを含むレスポンスの FacetBuckets。 |
ファセット バケット
ファセットのバケットはオペレーションの基本単位です。バケットは、バケット化されたフィールドのタイプに応じて、単一の値または連続する値の範囲で構成されます。現在、FacetBucket はレスポンス オブジェクトを返す場合にのみ使用されます。
JSON 表現 |
---|
{
"count": integer,
"percentage": integer,
"value": {
object ( |
フィールド | |
---|---|
count |
バケットの値と一致する結果の数。カウントは、カウントの精度が保証されている場合にのみ検索に対して返されます。Cloud Search では、クエリのファセット数が保証されていません。また、同じクエリであっても、ファセットカウントが断続的にしか行われない可能性があります。ファセット数の存在の依存関係は構築しないでください。代わりに、常に返されるファセットのパーセンテージを使用してください。 |
percentage |
バケットの値に一致する結果の割合。戻り値は(0 ~ 100] で、小数の場合は切り捨てられます。値を明示的に返されない場合は、0 に丸めた値をパーセンテージで表します。すべての検索に対して割合が返されますが、これはあくまで目安です。割合は常に返されるため、カウントではなく割合をレンダリングする必要があります。 |
value |
|
ResponseDebugInfo
レスポンスに関するデバッグ情報。
JSON 表現 |
---|
{ "formattedDebugInfo": string } |
フィールド | |
---|---|
formattedDebugInfo |
表示用の一般的なデバッグ情報。 |
ErrorInfo
レスポンスのエラー情報。
JSON 表現 |
---|
{
"errorMessages": [
{
object ( |
フィールド | |
---|---|
errorMessages[] |
|
ErrorMessage
ソース レスポンスごとのエラー メッセージ。
JSON 表現 |
---|
{
"source": {
object ( |
フィールド | |
---|---|
source |
|
errorMessage |
|
ResultCounts
結果の数に関する情報
JSON 表現 |
---|
{
"sourceResultCounts": [
{
object ( |
フィールド | |
---|---|
sourceResultCounts[] |
結果を持つ各ソースの結果カウント情報。 |
SourceResultCount
ソースごとの結果カウント情報。
JSON 表現 |
---|
{ "source": { object ( |
フィールド | |
---|---|
source |
結果カウントの情報が関連付けられているソース。 |
hasMoreResults |
このソースの検索結果がさらにあるかどうか。 |
共用体フィールド
|
|
resultCountEstimate |
このソースの推定結果数。 |
resultCountExact |
このソースの正確な検索結果数。 |