Method: query.search

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": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
フィールド
requestOptions

object (RequestOptions)

検索アプリケーションやユーザーのタイムゾーンなどのリクエスト オプション。
query

string

未加工のクエリ文字列。サポートされている検索演算子については、演算子を使用して検索を絞り込むをご覧ください。
pageSize

integer

1 ページで返される検索結果の最大数。有効な値は 1 ～ 100 です。デフォルト値は 10 です。2,000 を超える結果がリクエストされる場合、最小値は 50 です。
start

integer

結果の開始インデックス。
dataSourceRestrictions[]

object (DataSourceRestriction)

クエリに使用するソース。指定しない場合、現在の検索アプリケーションのすべてのデータソースが使用されます。
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

検索結果の並べ替えオプション
queryInterpretationOptions

object (QueryInterpretationOptions)

クエリを解釈するためのオプションが用意されています。
contextAttributes[]

object (ContextAttribute)

検索結果のランキングを調整するリクエストのコンテキスト属性。要素の最大数は 10 です。

レスポンスの本文

成功すると、レスポンスの本文に次の構造のデータが含まれます。

検索 API レスポンス。

JSON 表現 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
フィールド
queryInterpretation

object (QueryInterpretation)

ユーザークエリのクエリ解釈結果。クエリ解釈が無効になっている場合は空になります。
results[]

object (SearchResult)

検索クエリの結果。
structuredResults[]

object (StructuredResult)

ユーザークエリに対する構造化された結果。これらの結果は pageSize にはカウントされません。
spellResults[]

object (SpellResult)

クエリのスペル候補。
facetResults[]

object (FacetResult)

ファセットの結果の繰り返し。
hasMoreResults

boolean

クエリに一致する検索結果が他にもあるかどうか。
debugInfo

object (ResponseDebugInfo)

レスポンスに関するデバッグ情報。
errorInfo

object (ErrorInfo)

レスポンスに関するエラー情報。
resultCounts

object (ResultCounts)

展開された結果数情報。

共用体フィールド result_count。リクエストされたすべてのデータソースの合計結果数。クエリ対象のデータソースのセットに事前定義のソースが含まれる場合は省略されます。次の状況では、結果の件数が正確な数ではなく推定値として返される可能性があります。

  • 1 つのフレーズに 3 つ以上の用語が含まれる場合（例: 「正確な結果数」は引用符で囲む）。

  • 評価する一意の検索結果 ACL の数が多すぎて、妥当な遅延時間内に計算できない場合。

システムがすべてのドキュメントを検索できないというまれなケースで、クエリを再実行します。result_count は次のいずれかになります。
resultCountEstimate

string (int64 format)

このクエリの推定結果数。
resultCountExact

string (int64 format)

このクエリの正確な結果数。

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

詳細については、承認ガイドをご覧ください。

QueryInterpretationOptions

クエリを解釈するためのオプションが用意されています。

JSON 表現 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
フィールド
disableNlInterpretation

boolean

クエリの自然言語（NL）解釈を無効にするフラグ。デフォルトは false です。true に設定すると、自然言語の解釈が無効になります。オランダ語の解釈は、事前定義されたデータソースにのみ適用されます。
enableVerbatimMode

boolean

クエリの自然言語（NL）解釈、補完結果の取得、カスタムの類義語の使用など、内部の最適化をすべて無効にするには、このフラグを有効にします。2 つのフラグのいずれかが true の場合、Nl の解釈は無効になります。
disableSupplementalResults

boolean

クエリの補足結果を無効にするには、このフラグを使用します。True に設定すると、SearchApplication レベルで選択された補完結果の設定が優先されます。

QueryInterpretation

JSON 表現 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
フィールド
interpretedQuery

string

検索に使用されたクエリの解釈。たとえば、「email from john」のような自然言語インテントを持つクエリは「from:john source:mail」と解釈されます。理由が NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY の場合、このフィールドは入力されません。
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

クエリが解釈された理由。解釈タイプが NONE でない場合、このフィールドは UNSPECIFIED にはなりません。

QueryInterpretation.InterpretationType

列挙型
NONE 検索結果の取得に、自然言語の解釈もクエリのより広範なバージョンも使用されません。
BLEND 元のクエリの結果が他の結果と統合されます。これらの他の結果を元のクエリの結果と統合する理由は、以下の [理由] フィールドに入力されます。
REPLACE 元のクエリの結果が置き換えられます。元のクエリの結果を置き換える理由は、以下の [理由] フィールドに入力されます。

QueryInterpretation.Reason

列挙型
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT 自然言語でクエリに解釈されて検索結果が取得されます。
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY クエリとドキュメントの語句の類似性は、ユーザーのクエリに対して十分な結果が見つからなかったため、クエリを選択的に広げて追加の検索結果を取得するために使用されます。この場合、解釈されたクエリは空になります。

SearchResult

ドキュメントのインデックス登録された情報を含む結果。

JSON 表現 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
フィールド
title

string

検索結果のタイトル。
url

string

検索結果の URL。この URL には、実際のアイテムへの Google のリダイレクトが含まれています。この URL は署名されているため、変更しないでください。
snippet

object (Snippet)

この結果について利用可能なすべてのスニペット（要約）を連結したもの。
metadata

object (Metadata)

指定します。
clusteredResults[]

object (SearchResult)

ソースがクラスタ化されている場合は、クラスタ化結果のリストを提供します。クラスタ化結果は 1 レベルのみ表示されます。現在のソースがクラスタリングに対して有効になっていない場合、このフィールドは空になります。
debugInfo

object (ResultDebugInfo)

この検索結果に関するデバッグ情報。

snippet

ページのコンテンツを要約した検索結果のスニペット。

JSON 表現 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
フィールド
snippet

string

ドキュメントのスニペット。ドキュメントのスニペット。レンダリング前にエスケープする必要があるエスケープされた HTML 文字が含まれている場合があります。
matchRanges[]

object (MatchRange)

スニペット内で一致した範囲。

MatchRange

スニペットの範囲（start、end）と一致しました。

JSON 表現 
{
  "start": integer,
  "end": integer
}
フィールド
start

integer

スニペット内での一致の開始位置。
end

integer

スニペットにおける一致の終了。

メタデータ

メタデータが含まれます。

JSON 表現 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
フィールド
source

object (Source)

結果の名前付きソース（Gmail など）。
mimeType

string

検索結果の MIME タイプ。
thumbnailUrl

string

結果のサムネイル URL。
owner

object (Person)

検索結果のドキュメントまたはオブジェクトのオーナー（通常は作成者）です。
createTime

string (Timestamp format)

検索結果でのこのドキュメントまたはオブジェクトの作成時間。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

検索結果におけるオブジェクトの最終更新日。設定されていない場合、ここで返される値は空です。updateTime が鮮度の計算に使用され、設定されていない場合、この値はデフォルトで現在の時刻から 2 年後に設定されます。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"。
fields[]

object (NamedProperty)

構造化データ内のインデックス付きフィールド。汎用的な名前付きプロパティとして返されます。
displayOptions

object (ResultDisplayMetadata)

構造化データの検索結果の表示方法を指定するオプションです。
objectType

string

検索結果のオブジェクト タイプ。

ResultDisplayMetadata

JSON 表現 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
フィールド
objectTypeLabel

string

オブジェクトの表示ラベル。
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

結果とともに表示されるメタライン コンテンツ。

ResultDisplayMetadata.ResultDisplayLine

表示される行を構成するフィールドのコレクション

JSON 表現 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
フィールド
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

query.search 結果の表示フィールド

JSON 表現 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
フィールド
label

string

プロパティの表示ラベル。
operatorName

string

プロパティの演算子名。
property

object (NamedProperty)

プロパティの名前と値のペア。

ResultDebugInfo

結果に関するデバッグ情報。

JSON 表現 
{
  "formattedDebugInfo": string
}
フィールド
formattedDebugInfo

string

ディスプレイ用にフォーマットされた一般的なデバッグ情報。

StructuredResult

検索リクエストの一部として返される構造化された結果です。

JSON 表現 
{
  "person": {
    object (Person)
  }
}
フィールド
person

object (Person)

人物の描写

SpellResult

JSON 表現 
{
  "suggestedQuery": string
}
フィールド
suggestedQuery

string

クエリのスペル候補。

FacetResult

ソース固有のファセット レスポンス

JSON 表現 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
フィールド
sourceName

string

ファセットの結果を返すソース名。空にはできません。
objectType

string

ファセットの結果を返すオブジェクト タイプ。これは空でもかまいません。
operatorName

string

ファセットに選択された演算子の名前。@参照: cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

対応するフィルタを持つ 1 つ以上の結果を含むレスポンスの値の FacetBuckets。

FacetBucket

ファセットのバケットは操作の基本単位です。バケットは、バケット化されたフィールドのタイプに応じて、単一の値または連続した範囲の値のいずれかで構成されます。FacetBucket は現在のところ、レスポンス オブジェクトを返すためにのみ使用されます。

JSON 表現 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
フィールド
count

integer

バケットの値に一致する結果の数。カウント数は、カウントの正確性が保証されている場合にのみ、検索に対して返されます。Cloud Search では、すべてのクエリのファセット カウントが保証されるわけではありません。また、同じクエリであっても、ファセット カウントが断続的に表示される場合があります。ファセット カウントの存在に依存せず、常に返されるファセット パーセンテージを使用します。
percentage

integer

バケットの値に一致する結果の割合。戻り値は（0 ～ 100]）で、小数点以下の場合は整数に切り捨てられます。値を明示的に返しない場合は、パーセント値で 0 に丸めます。パーセンテージはすべての検索に対して返されますが、これは推定値です。パーセンテージは常に返されるため、カウントではなくパーセンテージをレンダリングしてください。
filter

object (Filter)

対応するバケットが選択されている場合に、検索リクエストで渡すフィルタ。
value

object (Value)

ResponseDebugInfo

レスポンスに関するデバッグ情報。

JSON 表現 
{
  "formattedDebugInfo": string
}
フィールド
formattedDebugInfo

string

ディスプレイ用にフォーマットされた一般的なデバッグ情報。

ErrorInfo

レスポンスに関するエラー情報。

JSON 表現 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
フィールド
errorMessages[]

object (ErrorMessage)

ErrorMessage

ソース レスポンスごとのエラー メッセージ。

JSON 表現 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
フィールド
source

object (Source)
errorMessage

string

ResultCounts

結果数の情報

JSON 表現 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
フィールド
sourceResultCounts[]

object (SourceResultCount)

結果を含む各ソースの結果数情報。

SourceResultCount

ソースごとの結果数の情報。

JSON 表現 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
フィールド
source

object (Source)

結果数情報が関連付けられているソース。
hasMoreResults

boolean

このソースの検索結果が他にもあるかどうか。

共用体フィールド result_count。

result_count は次のいずれかになります。
resultCountEstimate

string (int64 format)

このソースの推定結果数。
resultCountExact

string (int64 format)

このソースの正確な結果数。