- HTTP リクエスト
- リクエストの本文
- レスポンスの本文
- 承認スコープ
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.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 です。 |
レスポンスの本文
成功すると、レスポンスの本文に次の構造のデータが含まれます。
検索 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
詳細については、承認ガイドをご覧ください。
QueryInterpretationOptions
クエリを解釈するためのオプションが用意されています。
JSON 表現 |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
フィールド | |
---|---|
disableNlInterpretation |
クエリの自然言語(NL)解釈を無効にするフラグ。デフォルトは false です。true に設定すると、自然言語の解釈が無効になります。オランダ語の解釈は、事前定義されたデータソースにのみ適用されます。 |
enableVerbatimMode |
クエリの自然言語(NL)解釈、補完結果の取得、カスタムの類義語の使用など、内部の最適化をすべて無効にするには、このフラグを有効にします。2 つのフラグのいずれかが true の場合、Nl の解釈は無効になります。 |
disableSupplementalResults |
クエリの補足結果を無効にするには、このフラグを使用します。True に設定すると、SearchApplication レベルで選択された補完結果の設定が優先されます。 |
QueryInterpretation
JSON 表現 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
フィールド | |
---|---|
interpretedQuery |
検索に使用されたクエリの解釈。たとえば、「email from john」のような自然言語インテントを持つクエリは「from:john source:mail」と解釈されます。理由が NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY の場合、このフィールドは入力されません。 |
interpretationType |
|
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 ( |
フィールド | |
---|---|
title |
検索結果のタイトル。 |
url |
検索結果の URL。この URL には、実際のアイテムへの Google のリダイレクトが含まれています。この URL は署名されているため、変更しないでください。 |
snippet |
この結果について利用可能なすべてのスニペット(要約)を連結したもの。 |
metadata |
指定します。 |
clusteredResults[] |
ソースがクラスタ化されている場合は、クラスタ化結果のリストを提供します。クラスタ化結果は 1 レベルのみ表示されます。現在のソースがクラスタリングに対して有効になっていない場合、このフィールドは空になります。 |
debugInfo |
この検索結果に関するデバッグ情報。 |
snippet
ページのコンテンツを要約した検索結果のスニペット。
JSON 表現 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
フィールド | |
---|---|
snippet |
ドキュメントのスニペット。ドキュメントのスニペット。レンダリング前にエスケープする必要があるエスケープされた HTML 文字が含まれている場合があります。 |
matchRanges[] |
スニペット内で一致した範囲。 |
MatchRange
スニペットの範囲(start、end)と一致しました。
JSON 表現 |
---|
{ "start": integer, "end": integer } |
フィールド | |
---|---|
start |
スニペット内での一致の開始位置。 |
end |
スニペットにおける一致の終了。 |
メタデータ
メタデータが含まれます。
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 |
プロパティの名前と値のペア。 |
ResultDebugInfo
結果に関するデバッグ情報。
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 |
ファセットに選択された演算子の名前。@参照: cloudsearch.SchemaPropertyOptions |
buckets[] |
対応するフィルタを持つ 1 つ以上の結果を含むレスポンスの値の FacetBuckets。 |
FacetBucket
ファセットのバケットは操作の基本単位です。バケットは、バケット化されたフィールドのタイプに応じて、単一の値または連続した範囲の値のいずれかで構成されます。FacetBucket は現在のところ、レスポンス オブジェクトを返すためにのみ使用されます。
JSON 表現 |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
フィールド | |
---|---|
count |
バケットの値に一致する結果の数。カウント数は、カウントの正確性が保証されている場合にのみ、検索に対して返されます。Cloud Search では、すべてのクエリのファセット カウントが保証されるわけではありません。また、同じクエリであっても、ファセット カウントが断続的に表示される場合があります。ファセット カウントの存在に依存せず、常に返されるファセット パーセンテージを使用します。 |
percentage |
バケットの値に一致する結果の割合。戻り値は(0 ~ 100])で、小数点以下の場合は整数に切り捨てられます。値を明示的に返しない場合は、パーセント値で 0 に丸めます。パーセンテージはすべての検索に対して返されますが、これは推定値です。パーセンテージは常に返されるため、カウントではなくパーセンテージをレンダリングしてください。 |
filter |
対応するバケットが選択されている場合に、検索リクエストで渡すフィルタ。 |
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 |
このソースの正確な結果数。 |