Method: query.search

Cloud Search Query API menyediakan metode penelusuran, yang menampilkan hasil paling relevan dari kueri pengguna. Hasil penelusuran dapat berasal dari aplikasi Google Workspace, seperti Gmail atau Google Drive, atau dapat berasal dari data yang telah Anda indeks dari pihak ketiga.

Catatan: API ini memerlukan akun pengguna akhir standar untuk dieksekusi. Akun layanan tidak dapat menjalankan permintaan Query API secara langsung; untuk menggunakan akun layanan agar dapat menjalankan kueri, siapkan delegasi otoritas seluruh domain Google Workspace.

Permintaan HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

URL menggunakan sintaksis gRPC Transcoding.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi 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)
    }
  ]
}
Kolom
requestOptions

object (RequestOptions)

Opsi permintaan, seperti aplikasi penelusuran dan zona waktu pengguna.
query

string

String kueri mentah. Lihat operator penelusuran yang didukung di bagian Persempit penelusuran Anda dengan operator
pageSize

integer

Jumlah maksimum hasil penelusuran yang akan ditampilkan dalam satu halaman. Nilai yang valid adalah antara 1 dan 100, inklusif. Nilai defaultnya adalah 10. Nilai minimum adalah 50 ketika hasil yang melebihi 2000 diminta.
start

integer

Memulai indeks hasil.
dataSourceRestrictions[]

object (DataSourceRestriction)

Sumber yang akan digunakan untuk kueri. Jika tidak ditentukan, semua sumber data dari aplikasi penelusuran saat ini akan digunakan.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Opsi untuk mengurutkan hasil penelusuran
queryInterpretationOptions

object (QueryInterpretationOptions)

untuk menafsirkan kueri pengguna.
contextAttributes[]

object (ContextAttribute)

Atribut konteks untuk permintaan yang akan digunakan untuk menyesuaikan peringkat hasil penelusuran. Jumlah elemen maksimum adalah 10.

Isi respons

Jika berhasil, isi respons memuat data dengan struktur berikut:

Respons API penelusuran.

Representasi 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.
}
Kolom
queryInterpretation

object (QueryInterpretation)

Hasil interpretasi kueri untuk kueri pengguna. Kosong jika penafsiran kueri dinonaktifkan.
results[]

object (SearchResult)

Hasil dari kueri penelusuran.
structuredResults[]

object (StructuredResult)

Hasil terstruktur untuk kueri pengguna. Hasil ini tidak dihitung untuk pageSize.
spellResults[]

object (SpellResult)

Saran ejaan untuk kueri.
facetResults[]

object (FacetResult)

Hasil faset berulang.
hasMoreResults

boolean

Apakah ada hasil penelusuran lain yang cocok dengan kueri.
debugInfo

object (ResponseDebugInfo)

Men-debug informasi tentang respons.
errorInfo

object (ErrorInfo)

Informasi error tentang respons.
resultCounts

object (ResultCounts)

Informasi jumlah hasil yang diperluas.

Kolom union result_count. Total jumlah hasil di semua sumber data yang diminta. Dihilangkan jika sumber yang telah ditentukan disertakan dalam kumpulan sumber data yang dikueri. Jumlah hasil dapat ditampilkan sebagai estimasi, bukan secara persis, dalam situasi berikut:

  • Jika kueri memiliki lebih dari 2 istilah dalam frasa, seperti "jumlah hasil yang tepat" dalam tanda kutip.

  • Jika jumlah ACL hasil penelusuran unik yang dievaluasi terlalu besar untuk dihitung dalam latensi yang wajar.

Dalam kasus yang jarang terjadi, saat sistem tidak dapat menelusuri semua dokumen, jalankan kembali kueri. result_count hanya dapat berupa salah satu dari berikut:
resultCountEstimate

string (int64 format)

Perkiraan jumlah hasil untuk kueri ini.
resultCountExact

string (int64 format)

Jumlah hasil yang tepat untuk kueri ini.

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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

Untuk informasi selengkapnya, lihat Ringkasan OAuth 2.0.

QueryInterpretationOptions

untuk menafsirkan kueri pengguna.

Representasi JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Kolom
disableNlInterpretation

boolean

Tanda untuk menonaktifkan interpretasi natural language (NL) dari kueri. Defaultnya adalah false, Tetapkan ke true untuk menonaktifkan penafsiran bahasa alami. Interpretasi NL hanya berlaku untuk sumber data standar.
enableVerbatimMode

boolean

Aktifkan tanda ini untuk menonaktifkan semua pengoptimalan internal seperti interpretasi bahasa natural (NL) dari kueri, pengambilan hasil tambahan, dan penggunaan sinonim termasuk yang khusus. Penafsiran Nl akan dinonaktifkan jika salah satu dari kedua tanda adalah benar.
disableSupplementalResults

boolean

Gunakan tanda ini guna menonaktifkan hasil tambahan untuk kueri. Setelan hasil tambahan yang dipilih di tingkat SearchApplication akan diprioritaskan jika disetel ke Benar (True).

Penafsiran Kueri

Representasi JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Kolom
interpretedQuery

string

Penafsiran kueri yang digunakan dalam penelusuran. Misalnya, kueri dengan intent bahasa alami seperti "email dari john" akan ditafsirkan sebagai "from:john source:mail". Kolom ini tidak akan diisi jika alasannya NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Alasan penafsiran kueri. Kolom ini tidak akan DITENTUKAN jika jenis penafsiran TIDAK ADA.

QueryInterpretation.InterpretationType

Enumerasi
NONE Penafsiran bahasa alami atau versi kueri yang lebih luas tidak digunakan untuk mengambil hasil penelusuran.
BLEND Hasil dari kueri asli digabungkan dengan hasil lainnya. Alasan untuk menggabungkan hasil lain tersebut dengan hasil dari kueri asli akan diisi di kolom 'Alasan' di bawah.
REPLACE Hasil dari kueri asli akan diganti. Alasan penggantian hasil dari kueri asli diisi dalam kolom 'Alasan' di bawah.

QueryInterpretation.Reason

Enumerasi
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Penafsiran bahasa alami kueri digunakan untuk mengambil hasil penelusuran.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Kemiripan istilah dokumen dan kueri digunakan untuk memperluas kueri secara selektif guna mengambil hasil penelusuran tambahan karena hasil yang ditemukan untuk kueri pengguna tidak ditemukan. Kueri yang diinterpretasikan akan kosong untuk kasus ini.

Hasil Penelusuran

Hasil yang berisi informasi terindeks untuk dokumen.

Representasi JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Kolom
title

string

Judul hasil penelusuran.
url

string

URL hasil penelusuran. URL berisi pengalihan Google ke item sebenarnya. URL ini ditandatangani dan tidak boleh diubah.
snippet

object (Snippet)

Penyambungan semua cuplikan (ringkasan) yang tersedia untuk hasil ini.
metadata

object (Metadata)

metadata hasil penelusuran.
clusteredResults[]

object (SearchResult)

Jika sumber dikelompokkan, berikan daftar hasil yang dikelompokkan. Hanya akan ada satu tingkat hasil yang dikelompokkan. Jika sumber saat ini tidak diaktifkan untuk pengelompokan, kolom ini akan kosong.
debugInfo

object (ResultDebugInfo)

Men-debug informasi tentang hasil penelusuran ini.

Snippet

Cuplikan hasil penelusuran, yang merangkum konten halaman yang dihasilkan.

Representasi JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Kolom
snippet

string

Cuplikan dokumen. Cuplikan dokumen. Dapat berisi karakter HTML yang di-escape yang harus di-escape sebelum melakukan rendering.
matchRanges[]

object (MatchRange)

Rentang yang cocok dalam cuplikan.

PencocokanRentang

Rentang yang cocok dari cuplikan [awal, akhir).

Representasi JSON 
{
  "start": integer,
  "end": integer
}
Kolom
start

integer

Posisi awal kecocokan dalam cuplikan.
end

integer

Akhir kecocokan dalam cuplikan.

Metadata

metadata hasil penelusuran yang cocok.

Representasi JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Kolom
source

object (Source)

Sumber yang dinamai untuk hasil, seperti Gmail.
mimeType

string

Jenis mime hasil penelusuran.
thumbnailUrl

string

URL thumbnail hasil.
owner

object (Person)

pemilik (biasanya pembuat) dokumen atau objek hasil penelusuran.
createTime

string (Timestamp format)

Waktu pembuatan untuk dokumen atau objek ini dalam hasil penelusuran.

Stempel waktu dalam format RFC3339 UTC "Zulu", dengan resolusi nanodetik dan hingga sembilan digit pecahan. Contoh: "2014-10-02T15:01:23Z" dan "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Tanggal terakhir diubah untuk objek di hasil penelusuran. Jika tidak disetel di item, nilai yang ditampilkan di sini kosong. Jika updateTime digunakan untuk menghitung keaktualan dan nilai tidak ditetapkan, nilai ini akan ditetapkan secara default ke 2 tahun dari waktu saat ini.

Stempel waktu dalam format RFC3339 UTC "Zulu", dengan resolusi nanodetik dan hingga sembilan digit pecahan. Contoh: "2014-10-02T15:01:23Z" dan "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Kolom terindeks dalam data terstruktur, ditampilkan sebagai properti bernama generik.
displayOptions

object (ResultDisplayMetadata)

opsi yang menentukan cara menampilkan hasil penelusuran data terstruktur.
objectType

string

Jenis objek hasil penelusuran.

ResultDisplayMetadata

Representasi JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Kolom
objectTypeLabel

string

Label tampilan untuk objek.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Konten metaline akan ditampilkan dengan hasil.

ResultDisplayMetadata.ResultDisplayLine

Kumpulan kolom yang membentuk garis yang ditampilkan

Representasi JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Kolom
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Menampilkan Kolom untuk Hasil query.search

Representasi JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Kolom
label

string

Label tampilan untuk properti.
operatorName

string

Nama operator properti.
property

object (NamedProperty)

Pasangan nilai nama untuk properti.

InfoDebugHasil

Men-debug informasi tentang hasil.

Representasi JSON 
{
  "formattedDebugInfo": string
}
Kolom
formattedDebugInfo

string

Info debug umum diformat untuk ditampilkan.

Hasil Terstruktur

Hasil terstruktur yang ditampilkan sebagai bagian dari permintaan penelusuran.

Representasi JSON 
{
  "person": {
    object (Person)
  }
}
Kolom
person

object (Person)

Representasi seseorang

Hasil Ejaan

Representasi JSON 
{
  "suggestedQuery": string
}
Kolom
suggestedQuery

string

Ejaan kueri yang disarankan.

Hasil Facet

Respons faset khusus sumber

Representasi JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Kolom
sourceName

string

Nama sumber yang hasil fasetnya ditampilkan. Tidak akan kosong.
objectType

string

Jenis objek yang hasil fasetnya ditampilkan. Harus kosong.
operatorName

string

Nama operator yang dipilih untuk faset. @lihat cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBucket untuk nilai sebagai respons yang berisi setidaknya satu hasil dengan filter yang sesuai.

Bucket FacetBucket

Bucket dalam faset adalah unit operasi dasar. Bucket dapat terdiri dari nilai tunggal ATAU rentang nilai yang berdekatan, bergantung pada jenis kolom yang dikelompokkan. FacetBucket saat ini hanya digunakan untuk menampilkan objek respons.

Representasi JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Kolom
count

integer

Jumlah hasil yang cocok dengan nilai bucket. Jumlah hanya dikembalikan untuk penelusuran jika akurasi jumlah dipastikan. Cloud Search tidak menjamin jumlah faset untuk setiap kueri dan jumlah faset mungkin hanya ada sesekali, bahkan untuk kueri yang identik. Jangan mem-build dependensi pada keberadaan jumlah faset; sebagai gantinya, gunakan persentase facet ount yang selalu ditampilkan.
percentage

integer

Persentase hasil yang cocok dengan nilai bucket. Nilai yang ditampilkan adalah antara (0-100], dan dibulatkan ke bawah menjadi bilangan bulat jika pecahan. Jika nilai tidak ditampilkan secara eksplisit, nilai tersebut mewakili nilai persentase yang dibulatkan ke 0. Persentase ditampilkan untuk semua penelusuran, namun merupakan perkiraan. Karena persentase selalu ditampilkan, Anda harus merender persentase, bukan jumlah.
filter

object (Filter)

Filter yang akan diteruskan dalam permintaan penelusuran jika bucket yang sesuai dipilih.
value

object (Value)

ResponsDebugInfo

Men-debug informasi tentang respons.

Representasi JSON 
{
  "formattedDebugInfo": string
}
Kolom
formattedDebugInfo

string

Info debug umum diformat untuk ditampilkan.

InfoError

Informasi error tentang respons.

Representasi JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Kolom
errorMessages[]

object (ErrorMessage)

PesanError

Pesan error per respons sumber.

Representasi JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Kolom
source

object (Source)
errorMessage

string

JumlahHasil

Informasi jumlah hasil

Representasi JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Kolom
sourceResultCounts[]

object (SourceResultCount)

Informasi jumlah hasil untuk setiap sumber dengan hasil.

JumlahHasilSumber

Informasi jumlah hasil per sumber.

Representasi 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.
}
Kolom
source

object (Source)

Sumber yang terkait dengan informasi jumlah hasil.
hasMoreResults

boolean

Apakah ada hasil penelusuran lainnya untuk sumber ini.

Kolom union result_count.

result_count hanya dapat berupa salah satu dari berikut:
resultCountEstimate

string (int64 format)

Estimasi jumlah hasil untuk sumber ini.
resultCountExact

string (int64 format)

Jumlah hasil yang tepat untuk sumber ini.