- Yêu cầu HTTP
- Nội dung yêu cầu
- Nội dung phản hồi
- Phạm vi cấp phép
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Đoạn mã
- MatchRange
- Siêu dữ liệu
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult (Kết quả chính tả)
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Hãy làm thử!
Cloud Search Query API cung cấp phương thức tìm kiếm giúp trả về kết quả phù hợp nhất từ truy vấn của người dùng. Kết quả có thể đến từ các ứng dụng của Google Workspace, chẳng hạn như Gmail hoặc Google Drive, hoặc có thể từ dữ liệu của một bên thứ ba mà bạn đã lập chỉ mục.
Lưu ý: API này yêu cầu tài khoản người dùng cuối tiêu chuẩn để thực thi. Tài khoản dịch vụ không thể trực tiếp thực hiện các yêu cầu API Truy vấn. Để sử dụng tài khoản dịch vụ để thực hiện truy vấn, hãy thiết lập tính năng uỷ quyền trên toàn miền của Google Workspace.
Yêu cầu HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
URL sử dụng cú pháp Chuyển mã gRPC.
Nội dung yêu cầu
Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{ "requestOptions": { object ( |
Các trường | |
---|---|
requestOptions |
Tuỳ chọn yêu cầu, chẳng hạn như ứng dụng tìm kiếm và múi giờ của người dùng. |
query |
Chuỗi truy vấn thô. Xem các toán tử tìm kiếm được hỗ trợ trong phần Thu hẹp tìm kiếm của bạn bằng toán tử |
pageSize |
Số lượng kết quả tìm kiếm tối đa được trả về trong một trang. Giá trị hợp lệ nằm trong khoảng từ 1 đến 100. Giá trị mặc định là 10. Giá trị tối thiểu là 50 khi yêu cầu kết quả sau 2000. |
start |
Chỉ mục bắt đầu của kết quả. |
dataSourceRestrictions[] |
Các nguồn cần sử dụng để truy vấn. Nếu bạn không chỉ định, tất cả nguồn dữ liệu từ ứng dụng tìm kiếm hiện tại sẽ được sử dụng. |
facetOptions[] |
|
sortOptions |
Tuỳ chọn để sắp xếp kết quả tìm kiếm |
queryInterpretationOptions |
để diễn giải truy vấn của người dùng. |
contextAttributes[] |
Các thuộc tính bối cảnh cho yêu cầu sẽ được dùng để điều chỉnh thứ hạng của kết quả tìm kiếm. Số lượng phần tử tối đa là 10. |
Nội dung phản hồi
Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:
Phản hồi của API Tìm kiếm.
Biểu diễn dưới dạng JSON |
---|
{ "queryInterpretation": { object ( |
Các trường | |
---|---|
queryInterpretation |
Kết quả diễn giải truy vấn cho truy vấn của người dùng. Để trống nếu phần diễn giải cụm từ tìm kiếm bị tắt. |
results[] |
Kết quả từ một cụm từ tìm kiếm. |
structuredResults[] |
Kết quả có cấu trúc cho cụm từ tìm kiếm của người dùng. Những kết quả này không được tính vào pageSize. |
spellResults[] |
Cách viết chính tả đề xuất cho truy vấn. |
facetResults[] |
Kết quả thuộc tính lặp lại. |
hasMoreResults |
Liệu có thêm kết quả tìm kiếm nào khớp với cụm từ tìm kiếm hay không. |
debugInfo |
Thông tin gỡ lỗi về phản hồi. |
errorInfo |
Thông tin lỗi về phản hồi. |
resultCounts |
Thông tin mở rộng về số lượng kết quả. |
Trường nhóm
Trong một số ít trường hợp, khi hệ thống không thể tìm kiếm trong tất cả các tài liệu, hãy chạy lại truy vấn. |
|
resultCountEstimate |
Số lượng kết quả ước tính cho cụm từ tìm kiếm này. |
resultCountExact |
Số kết quả chính xác cho cụm từ tìm kiếm này. |
Phạm vi uỷ quyền
Yêu cầu một trong các phạm vi OAuth sau:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.
QueryInterpretationOptions
để diễn giải truy vấn của người dùng.
Biểu diễn dưới dạng JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Các trường | |
---|---|
disableNlInterpretation |
Gắn cờ để tắt tính năng diễn giải ngôn ngữ tự nhiên (NL) cho các cụm từ tìm kiếm. Mặc định là false, Đặt thành true để tắt tính năng diễn giải ngôn ngữ tự nhiên. Việc diễn giải NL chỉ áp dụng cho các nguồn dữ liệu được xác định trước. |
enableVerbatimMode |
Bật cờ này để tắt tất cả các tính năng tối ưu hoá nội bộ, chẳng hạn như diễn giải truy vấn bằng ngôn ngữ tự nhiên (NL), truy xuất kết quả bổ sung và sử dụng các từ đồng nghĩa bao gồm cả các từ tuỳ chỉnh. Phiên diễn giải Nl sẽ bị tắt nếu một trong hai cờ là đúng. |
disableSupplementalResults |
Sử dụng cờ này để tắt kết quả bổ sung cho một truy vấn. Chế độ cài đặt kết quả bổ sung được chọn ở cấp SearchApplication sẽ được ưu tiên nếu bạn đặt thành True. |
QueryInterpretation
Biểu diễn dưới dạng JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Các trường | |
---|---|
interpretedQuery |
Diễn giải cụm từ tìm kiếm được dùng trong nội dung tìm kiếm. Ví dụ: cụm từ tìm kiếm với mục đích sử dụng ngôn ngữ tự nhiên như "email from john" sẽ được hiểu là "from:john source:mail". Trường này sẽ không được điền khi lý do là NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
reason |
Lý do diễn giải cụm từ tìm kiếm. Trường này sẽ không là KHÔNG XÁC ĐỊNH nếu loại nội dung diễn giải không phải là KHÔNG CÓ. |
QueryInterpretation.InterpretationType
Enum | |
---|---|
NONE |
Cả cách diễn giải ngôn ngữ tự nhiên và phiên bản rộng hơn của cụm từ tìm kiếm đều không được dùng để tìm nạp kết quả tìm kiếm. |
BLEND |
Các kết quả từ truy vấn ban đầu được kết hợp với các kết quả khác. Lý do cho việc kết hợp những kết quả khác này với kết quả từ truy vấn ban đầu được điền vào trường "Lý do" bên dưới. |
REPLACE |
Kết quả từ truy vấn ban đầu đã bị thay thế. Lý do thay thế kết quả từ truy vấn ban đầu được điền vào trường "Lý do" bên dưới. |
QueryInterpretation.Reason
Enum | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
Việc diễn giải ngôn ngữ tự nhiên của cụm từ tìm kiếm được dùng để tìm nạp kết quả tìm kiếm. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
Độ tương đồng của các thuật ngữ truy vấn và tài liệu được dùng để mở rộng một cách có chọn lọc cụm từ tìm kiếm nhằm truy xuất các kết quả tìm kiếm khác vì hệ thống không tìm thấy đủ kết quả cho truy vấn của người dùng. Trong trường hợp này, truy vấn được diễn giải sẽ trống. |
SearchResult
Kết quả chứa thông tin được lập chỉ mục cho một tài liệu.
Biểu diễn dưới dạng JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
Các trường | |
---|---|
title |
Tiêu đề của kết quả tìm kiếm. |
url |
URL của kết quả tìm kiếm. URL chứa lệnh chuyển hướng của Google đến mặt hàng thực tế. URL này đã được ký và không nên thay đổi. |
snippet |
Mối nối của tất cả các đoạn mã (tóm tắt) có sẵn cho kết quả này. |
metadata |
siêu dữ liệu của kết quả tìm kiếm. |
clusteredResults[] |
Nếu nguồn được phân nhóm, hãy cung cấp danh sách các kết quả được phân cụm. Sẽ chỉ có một cấp kết quả được nhóm. Nếu nguồn hiện tại không được bật để phân nhóm, trường này sẽ trống. |
debugInfo |
Thông tin gỡ lỗi về kết quả tìm kiếm này. |
Đoạn trích
Đoạn trích của kết quả tìm kiếm, tóm tắt nội dung của trang kết quả.
Biểu diễn dưới dạng JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
Các trường | |
---|---|
snippet |
Đoạn trích của tài liệu. Đoạn trích của tài liệu. Có thể chứa ký tự HTML đã thoát cần không thoát trước khi hiển thị. |
matchRanges[] |
Dải ô phù hợp trong đoạn mã. |
MatchRange
Phạm vi phù hợp của đoạn mã [bắt đầu, kết thúc).
Biểu diễn dưới dạng JSON |
---|
{ "start": integer, "end": integer } |
Các trường | |
---|---|
start |
Vị trí bắt đầu của kết quả trùng khớp trong đoạn mã. |
end |
Kết thúc trận đấu trong đoạn mã. |
Metadata
siêu dữ liệu của kết quả tìm kiếm trùng khớp.
Biểu diễn dưới dạng JSON |
---|
{ "source": { object ( |
Các trường | |
---|---|
source |
Nguồn được đặt tên của kết quả, chẳng hạn như Gmail. |
mimeType |
Loại Mime của kết quả tìm kiếm. |
thumbnailUrl |
URL hình thu nhỏ của kết quả. |
owner |
chủ sở hữu (thường là người tạo) tài liệu hoặc đối tượng của kết quả tìm kiếm. |
createTime |
Thời gian tạo tài liệu hoặc đối tượng này trong kết quả tìm kiếm. Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, với độ phân giải nano giây và tối đa 9 chữ số phân số. Ví dụ: |
updateTime |
Ngày sửa đổi gần đây nhất cho đối tượng trong kết quả tìm kiếm. Nếu không được đặt trong mục, giá trị được trả về ở đây sẽ trống. Khi Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, với độ phân giải nano giây và tối đa 9 chữ số phân số. Ví dụ: |
fields[] |
Các trường được lập chỉ mục trong dữ liệu có cấu trúc được trả về dưới dạng một thuộc tính được đặt tên chung. |
displayOptions |
chỉ định cách hiển thị kết quả tìm kiếm dữ liệu có cấu trúc. |
objectType |
Loại đối tượng của kết quả tìm kiếm. |
ResultDisplayMetadata
Biểu diễn dưới dạng JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Các trường | |
---|---|
objectTypeLabel |
Nhãn hiển thị cho đối tượng. |
metalines[] |
Nội dung metaline sẽ hiển thị cùng với kết quả. |
ResultDisplayMetadata.ResultDisplayLine
Tập hợp các trường tạo thành một dòng hiển thị
Biểu diễn dưới dạng JSON |
---|
{
"fields": [
{
object ( |
Các trường | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Các trường hiển thị cho kết quả query.search
Biểu diễn dưới dạng JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Các trường | |
---|---|
label |
Nhãn hiển thị cho cơ sở lưu trú. |
operatorName |
Tên toán tử của thuộc tính. |
property |
Cặp tên giá trị cho tài sản. |
ResultDebugInfo
Thông tin gỡ lỗi về kết quả.
Biểu diễn dưới dạng JSON |
---|
{ "formattedDebugInfo": string } |
Các trường | |
---|---|
formattedDebugInfo |
Thông tin gỡ lỗi chung được định dạng để hiển thị. |
StructuredResult
Kết quả có cấu trúc được trả về theo yêu cầu tìm kiếm.
Biểu diễn dưới dạng JSON |
---|
{
"person": {
object ( |
Các trường | |
---|---|
person |
Hình ảnh một người |
SpellResult
Biểu diễn dưới dạng JSON |
---|
{ "suggestedQuery": string } |
Các trường | |
---|---|
suggestedQuery |
Cách viết chính tả đề xuất của cụm từ tìm kiếm. |
FacetResult
Phản hồi thuộc tính cụ thể theo nguồn
Biểu diễn dưới dạng JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Các trường | |
---|---|
sourceName |
Tên nguồn mà kết quả thuộc tính được trả về. Sẽ không được để trống. |
objectType |
Loại đối tượng mà kết quả thuộc tính được trả về. Có thể để trống. |
operatorName |
Tên của toán tử được chọn để phân mặt. @xem cloudsearch.SchemaPropertyOptions |
buckets[] |
Nhóm thuộc tính cho các giá trị trong phản hồi có chứa ít nhất một kết quả với bộ lọc tương ứng. |
FacetBucket
Bộ chứa trong một thuộc tính là đơn vị hoạt động cơ bản. Một nhóm có thể bao gồm một giá trị duy nhất HOẶC một dải giá trị liền kề, tuỳ thuộc vào loại trường được phân giỏ. FacetBucket hiện chỉ được dùng để trả về đối tượng phản hồi.
Biểu diễn dưới dạng JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Các trường | |
---|---|
count |
Số lượng kết quả khớp với giá trị nhóm. Số lượng chỉ được trả về cho các lượt tìm kiếm khi đảm bảo tính chính xác về số lượng. Cloud Search không đảm bảo số lượng thuộc tính cho bất kỳ truy vấn nào và số lượng thuộc tính có thể chỉ xuất hiện không liên tục, ngay cả đối với các truy vấn giống nhau. Không tạo các phần phụ thuộc trên sự tồn tại của số lượng thuộc tính; thay vào đó, hãy sử dụng tỷ lệ phần trăm thuộc tính luôn được trả về. |
percentage |
Tỷ lệ phần trăm kết quả khớp với giá trị nhóm. Giá trị được trả về nằm trong khoảng (0-100] và được làm tròn xuống một số nguyên nếu là phân số. Nếu giá trị không được trả về rõ ràng, thì nó biểu thị giá trị phần trăm được làm tròn thành 0. Tỷ lệ phần trăm được trả về cho tất cả tìm kiếm, nhưng chỉ là ước tính. Vì tỷ lệ phần trăm luôn được trả về, bạn nên hiển thị tỷ lệ phần trăm thay vì số lượng. |
filter |
Bộ lọc sẽ được chuyển vào yêu cầu tìm kiếm nếu nhóm tương ứng được chọn. |
value |
|
ResponseDebugInfo
Thông tin gỡ lỗi về phản hồi.
Biểu diễn dưới dạng JSON |
---|
{ "formattedDebugInfo": string } |
Các trường | |
---|---|
formattedDebugInfo |
Thông tin gỡ lỗi chung được định dạng để hiển thị. |
ErrorInfo
Thông tin lỗi về phản hồi.
Biểu diễn dưới dạng JSON |
---|
{
"errorMessages": [
{
object ( |
Các trường | |
---|---|
errorMessages[] |
|
ErrorMessage
Thông báo lỗi cho mỗi phản hồi của nguồn.
Biểu diễn dưới dạng JSON |
---|
{
"source": {
object ( |
Các trường | |
---|---|
source |
|
errorMessage |
|
ResultCounts
Thông tin về số lượng kết quả
Biểu diễn dưới dạng JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Các trường | |
---|---|
sourceResultCounts[] |
Thông tin về số lượng kết quả cho mỗi nguồn có kết quả. |
SourceResultCount
Thông tin về số lượng kết quả trên mỗi nguồn.
Biểu diễn dưới dạng JSON |
---|
{ "source": { object ( |
Các trường | |
---|---|
source |
Nguồn liên kết với thông tin về số lượng kết quả. |
hasMoreResults |
Liệu có thêm kết quả tìm kiếm cho nguồn này hay không. |
Trường nhóm
|
|
resultCountEstimate |
Số kết quả ước tính cho nguồn này. |
resultCountExact |
Số lượng kết quả chính xác cho nguồn này. |