Method: query.search

Cloud Search Query API cung cấp phương thức tìm kiếm, phương thức này sẽ trả về kết quả có liên quan 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 như Gmail hoặc Google Drive, hoặc có thể đến từ dữ liệu mà bạn đã lập chỉ mục từ một bên thứ ba.

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 một tài khoản dịch vụ nhằm thực hiện truy vấn, hãy thiết lập chế độ 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 (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Trường
requestOptions

object (RequestOptions)

Các 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

string

Chuỗi truy vấn thô. Xem các toán tử tìm kiếm được hỗ trợ trong bài viết Thu hẹp phạm vi tìm kiếm bằng toán tử
pageSize

integer

Số kết quả tìm kiếm tối đa trả về trong một trang. Các 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ả vượt quá 2000.
start

integer

Chỉ mục bắt đầu của kết quả.
dataSourceRestrictions[]

object (DataSourceRestriction)

Các nguồn cần sử dụng để truy vấn. Nếu không được 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[]

object (FacetOptions)
sortOptions

object (SortOptions)

Các tuỳ chọn để sắp xếp kết quả tìm kiếm
queryInterpretationOptions

object (QueryInterpretationOptions)

để diễn giải truy vấn của người dùng.
contextAttributes[]

object (ContextAttribute)

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 (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.
}
Trường
queryInterpretation

object (QueryInterpretation)

Kết quả diễn giải cụm từ tìm kiếm cho cụm từ tìm kiếm của người dùng. trống nếu tính năng diễn giải cụm từ tìm kiếm bị tắt.
results[]

object (SearchResult)

Kết quả từ một cụm từ tìm kiếm.
structuredResults[]

object (StructuredResult)

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[]

object (SpellResult)

Chính tả đề xuất cho truy vấn.
facetResults[]

object (FacetResult)

Kết quả thuộc tính lặp lại.
hasMoreResults

boolean

Có thêm kết quả tìm kiếm nào phù hợp với cụm từ tìm kiếm hay không.
debugInfo

object (ResponseDebugInfo)

Thông tin gỡ lỗi về phản hồi.
errorInfo

object (ErrorInfo)

Thông tin về lỗi liên quan đến câu trả lời này.
resultCounts

object (ResultCounts)

Thông tin về số kết quả mở rộng.

Trường kết hợp result_count. Tổng số kết quả trên tất cả các nguồn dữ liệu được yêu cầu. Được bỏ qua nếu các nguồn được xác định trước có trong tập hợp các nguồn dữ liệu được truy vấn. Số lượng kết quả có thể được trả về dưới dạng số liệu ước tính, thay vì chính xác, trong các trường hợp sau:

  • Khi cụm từ tìm kiếm có nhiều hơn 2 cụm từ trong một cụm từ, chẳng hạn như "số lượng kết quả chính xác" trong dấu ngoặc kép.

  • Khi số lượng ACL kết quả tìm kiếm duy nhất cần đánh giá quá lớn để tính toán trong độ trễ hợp lý.

Trong trường hợp hiếm hoi khi hệ thống không thể tìm kiếm qua tất cả các tài liệu, hãy chạy lại truy vấn. result_count chỉ có thể là một trong những trạng thái sau đây:
resultCountEstimate

string (int64 format)

Số lượng kết quả ước tính cho truy vấn này.
resultCountExact

string (int64 format)

Số lượng kết quả chính xác cho truy vấn này.

Phạm vi cấp phép

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
}
Trường
disableNlInterpretation

boolean

Gắn cờ để tắt tính năng diễn giải ngôn ngữ tự nhiên (NL) của các cụm từ tìm kiếm. Mặc định là false, Đặt thành true để tắt tính năng phiên dịch 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

boolean

Bật cờ này để tắt tất cả các tối ưu hóa nội bộ 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 từ đồng nghĩa bao gồm từ đồng nghĩa tùy chỉnh. Tính năng diễn giải Nl sẽ bị tắt nếu một trong hai cờ là đúng.
disableSupplementalResults

boolean

Sử dụng cờ này để tắt các 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 (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Trường
interpretedQuery

string

Cách diễn giải cụm từ tìm kiếm được dùng trong nội dung tìm kiếm. Ví dụ: truy vấn có ý định sử dụng ngôn ngữ tự nhiên như "email từ john" sẽ được hiểu là "from:john source:mail". Trường này sẽ không được điền khi lý do không phải là NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Lý do diễn giải cụm từ tìm kiếm. Trường này sẽ không là KHÔNG PHỔ BIẾN nếu loại diễn giải không phải là KHÔNG CÓ.

QueryInterpretation.InterpretationType

Enum
NONE Chúng tôi không sử dụng cách diễn giải ngôn ngữ tự nhiên hay phiên bản rộng hơn của cụm từ tìm kiếm để tìm nạp kết quả tìm kiếm.
BLEND 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 kết hợp các kết quả khác này với kết quả từ truy vấn ban đầu được điền trong trường "Lý do" trường bên dưới.
REPLACE Kết quả từ truy vấn ban đầu sẽ được thay thế. Lý do thay thế kết quả từ truy vấn ban đầu được điền trong mục "Lý do" trường bên dưới.

QueryInterpretation.Reason

Enum
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Hệ thống sử dụng tính năng diễn giải ngôn ngữ tự nhiên của cụm từ tìm kiếm để tìm nạp kết quả tìm kiếm.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Cụm từ tìm kiếm và cụm từ tài liệu giống nhau đượ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 kết quả tìm kiếm bổ sung vì không tìm thấy đủ kết quả cho truy vấn của người dùng. Truy vấn đã diễn giải sẽ trống trong trường hợp này.

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 (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Trường
title

string

Tiêu đề của kết quả tìm kiếm.
url

string

URL của kết quả tìm kiếm. URL này 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

object (Snippet)

Kết quả nối của tất cả đoạn trích (nội dung tóm tắt) có sẵn cho kết quả này.
metadata

object (Metadata)

siêu dữ liệu của kết quả tìm kiếm.
clusteredResults[]

object (SearchResult)

Nếu nguồn được phân cụm, hãy cung cấp danh sách kết quả được phân cụm. Sẽ chỉ có một cấp độ kết quả được nhóm lại. Nếu nguồn hiện tại không được bật để phân cụm, trường này sẽ trống.
debugInfo

object (ResultDebugInfo)

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 (MatchRange)
    }
  ]
}
Trường
snippet

string

Đ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 không nên thoát trước khi hiển thị.
matchRanges[]

object (MatchRange)

Các dải ô phù hợp trong đoạn mã.

MatchRange

Phạm vi trùng khớp của một đoạn thông tin [bắt đầu, kết thúc).

Biểu diễn dưới dạng JSON 
{
  "start": integer,
  "end": integer
}
Trường
start

integer

Vị trí bắt đầu của kết quả phù hợp trong đoạn mã.
end

integer

Kết thúc so khớp trong đoạn mã.

Metadata

siêu dữ liệu của kết quả tìm kiếm phù hợp.

Biểu diễn dưới dạng JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Trường
source

object (Source)

Nguồn được đặt tên cho kết quả, chẳng hạn như Gmail.
mimeType

string

Loại Mime của kết quả tìm kiếm.
thumbnailUrl

string

URL hình thu nhỏ của kết quả.
owner

object (Person)

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

string (Timestamp format)

Thời gian tạo cho tài liệu hoặc đối tượng này trong kết quả tìm kiếm.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Ngày sửa đổi gần đây nhất đối với đối tượng trong kết quả tìm kiếm. Nếu không được thiết lập trong mục, giá trị được trả về ở đây sẽ trống. Khi bạn không đặt updateTime để tính toán độ mới, thì giá trị này mặc định là 2 năm tính từ thời điểm hiện tại.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Các trường đã 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ên chung.
displayOptions

object (ResultDisplayMetadata)

các tuỳ chọn chỉ định cách hiển thị kết quả tìm kiếm dữ liệu có cấu trúc.
objectType

string

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 (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Trường
objectTypeLabel

string

Nhãn hiển thị cho đối tượng.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Nội dung metalines sẽ được 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 được hiển thị

Biểu diễn dưới dạng JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Trường
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

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 (NamedProperty)
  }
}
Trường
label

string

Nhãn hiển thị cho thuộc tính.
operatorName

string

Tên toán tử của thuộc tính.
property

object (NamedProperty)

Cặp giá trị tên cho thuộc tính.

ResultDebugInfo

Gỡ lỗi thông tin về kết quả.

Biểu diễn dưới dạng JSON 
{
  "formattedDebugInfo": string
}
Trường
formattedDebugInfo

string

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ề trong yêu cầu tìm kiếm.

Biểu diễn dưới dạng JSON 
{
  "person": {
    object (Person)
  }
}
Trường
person

object (Person)

Hình ảnh đại diện của một người

SpellResult

Biểu diễn dưới dạng JSON 
{
  "suggestedQuery": string
}
Trường
suggestedQuery

string

Cách viết đề xuất của cụm từ tìm kiếm.

FacetResult

Phản hồi thuộc tính cụ thể về nguồn

Biểu diễn dưới dạng JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Trường
sourceName

string

Tên nguồn trả về kết quả thuộc tính. Sẽ không được để trống.
objectType

string

Loại đối tượng trả về kết quả thuộc tính. Có thể để trống.
operatorName

string

Tên của toán tử được chọn để phân lớp. @xem Cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets cho các giá trị trong phản hồi có chứa ít nhất một kết quả duy nhất với bộ lọc tương ứng.

FacetBucket

Một bộ chứa trong một khía cạ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 nhau, tuỳ thuộc vào loại trường được nhóm. 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 (Filter)
  },
  "value": {
    object (Value)
  }
}
Trường
count

integer

Số lượng kết quả khớp với giá trị nhóm. Số lượng chỉ được trả về cho các tìm kiếm khi độ chính xác của số lượng được đảm bảo. 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 những truy vấn giống nhau. Không tạo phần phụ thuộc dựa 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 của thuộc tính luôn được trả về.
percentage

integer

Tỷ lệ phần trăm kết quả khớp với giá trị nhóm. Giá trị trả về nằm trong khoảng (0-100] và được làm tròn xuống số nguyên nếu là phân số. Nếu giá trị không được trả về một cách rõ ràng, thì giá trị này thể hiện giá trị phần trăm làm tròn thành 0. Tỷ lệ phần trăm được trả về cho tất cả lượt tìm kiếm, nhưng chỉ là giá trị ướ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

object (Filter)

Bộ lọc được chuyển vào yêu cầu tìm kiếm nếu bộ chứa tương ứng được chọn.
value

object (Value)

ResponseDebugInfo

Thông tin gỡ lỗi về phản hồi.

Biểu diễn dưới dạng JSON 
{
  "formattedDebugInfo": string
}
Trường
formattedDebugInfo

string

Thông tin gỡ lỗi chung được định dạng để hiển thị.

ErrorInfo

Thông tin về lỗi liên quan đến câu trả lời này.

Biểu diễn dưới dạng JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Trường
errorMessages[]

object (ErrorMessage)

ErrorMessage

Thông báo lỗi trên mỗi phản hồi nguồn.

Biểu diễn dưới dạng JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Trường
source

object (Source)
errorMessage

string

ResultCounts

Thông tin về số kết quả

Biểu diễn dưới dạng JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Trường
sourceResultCounts[]

object (SourceResultCount)

Thông tin số lượng kết quả cho mỗi nguồn kèm theo kết quả.

SourceResultCount

Thông tin về số lượng kết quả nguồn.

Biểu diễn dưới dạng 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.
}
Trường
source

object (Source)

Nguồn liên kết với thông tin về số lượng kết quả.
hasMoreResults

boolean

Liệu có thêm kết quả tìm kiếm cho nguồn này hay không.

Trường kết hợp result_count.

result_count chỉ có thể là một trong những trạng thái sau đây:
resultCountEstimate

string (int64 format)

Số lượng kết quả ước tính cho nguồn này.
resultCountExact

string (int64 format)

Số lượng kết quả chính xác cho nguồn này.