- Yêu cầu HTTP
- Nội dung yêu cầu
- Nội dung phản hồi
- Phạm vi uỷ quyền
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Đoạn trích
- MatchRange
- Siêu dữ liệu
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- SpellResult.SuggestionType
- SafeHtmlProto
- 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, trả về kết quả phù hợp nhất từ một cụm từ tìm kiếm 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ể đến từ dữ liệu mà bạn đã lập chỉ mục từ bên thứ ba.
Lưu ý: API này yêu cầu một 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ể thực hiện trực tiếp 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 quyền uỷ quyền trên toàn miền 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 với cấu trúc sau:
| Biểu diễn dưới dạng JSON |
|---|
{ "requestOptions": { object ( |
| Trường | |
|---|---|
requestOptions |
Các lựa 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 Dùng toán tử để thu hẹp phạm vi tìm kiếm |
pageSize |
Số lượng kết quả tìm kiếm tối đa cần 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 bạn yêu cầu kết quả vượt quá 2000. |
start |
Chỉ mục bắt đầu của kết quả. |
dataSourceRestrictions[] |
Các nguồn cần dùng để truy vấn. Nếu bạn không chỉ định, tất cả cá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 |
Các lựa chọn để sắp xếp kết quả tìm kiếm |
queryInterpretationOptions |
các lựa chọn để diễn giải câu hỏi của người dùng. |
contextAttributes[] |
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
Phản hồi của API tìm kiếm. NEXT id: 19
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:
| Biểu diễn dưới dạng JSON |
|---|
{ "queryInterpretation": { object ( |
| 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 tính năng diễn giải truy vấn bị tắt. |
results[] |
Kết quả của 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 cụm từ tìm kiếm. |
facetResults[] |
Kết quả khía cạ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 về số lượng kết quả được mở rộng. |
Trường nhóm
Trong trường hợp hiếm gặ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 truy vấn này. |
resultCountExact |
Số lượng 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.queryhttps://www.googleapis.com/auth/cloud_search
Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.
QueryInterpretationOptions
các lựa chọn để diễn giải câu hỏi của người dùng.
| Biểu diễn dưới dạng JSON |
|---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
| Trường | |
|---|---|
disableNlInterpretation |
Cờ để tắt tính năng diễn giải ngôn ngữ tự nhiên (NL) của các truy vấn. 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. Tính năng diễn giải ngôn ngữ tự nhiên 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 hoạt động tối ưu hoá nội bộ như diễn giải ngôn ngữ tự nhiên (NL) của cụm từ tìm kiếm, truy xuất kết quả bổ sung và sử dụng từ đồng nghĩa (bao gồm cả từ đồng nghĩa tuỳ chỉnh). Tính năng diễn giải ngôn ngữ tự nhiên sẽ bị tắt nếu một trong hai cờ này là true. |
disableSupplementalResults |
Sử dụng cờ này để tắt kết quả bổ sung cho một cụm từ tìm kiếm. 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 ( |
| Trường | |
|---|---|
interpretedQuery |
Nội dung diễn giải cụm từ tìm kiếm được dùng trong tìm kiếm. Ví dụ: những cụm từ tìm kiếm có ý định bằng ngôn ngữ tự nhiên như "email của 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 truy vấn. Trường này sẽ không phải là UNSPECIFIED nếu loại diễn giải không phải là NONE. |
interpretedQueryActualResultCount |
Số lượng kết quả thực tế được trả về theo truy vấn được diễn giải. |
interpretedQueryEstimatedResultCount |
Số lượng kết quả ước tính được trả về theo truy vấn được diễn giải. |
QueryInterpretation.InterpretationType
| Enum | |
|---|---|
NONE |
Cả cách diễn giải ngôn ngữ tự nhiên và phiên bản mở 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 |
Kết quả từ cụm từ tìm kiếm 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ừ cụm từ tìm kiếm ban đầu sẽ được điền vào trường "reason" (lý do) bên dưới. |
REPLACE |
Kết quả của cụm từ tìm kiếm ban đầu sẽ được thay thế. Lý do thay thế kết quả từ truy vấn ban đầu được điền sẵn trong trường "reason" (lý do) bên dưới. |
QueryInterpretation.Reason
| Enum | |
|---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
Tính năng 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 |
sự tương đồng giữa cụm từ tìm kiếm và cụm từ trong tài liệu được dùng để mở rộng có chọn lọc cụm từ tìm kiếm nhằm truy xuất thêm kết quả tìm kiếm vì không tìm thấy đủ kết quả cho cụm từ tìm kiếm của người dùng. Cụm từ tìm kiếm được 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. Next id: 16
| Biểu diễn dưới dạng JSON |
|---|
{ "title": string, "url": string, "snippet": { object ( |
| 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 một 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 được thay đổi. |
snippet |
Chuỗi nối của tất cả các đoạn trích (bản 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 cụm, hãy cung cấp danh sách kết quả được phân cụm. 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 cụm, thì 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 ( |
| Trường | |
|---|---|
snippet |
Đoạn trích của tài liệu. Có thể chứa ký tự HTML có mã thoát cần được giải mã trước khi hiển thị. |
matchRanges[] |
Các phạm vi trùng khớp trong đoạn mã. |
MatchRange
Phạm vi trùng khớp của một đoạn mã [start, end).
| Biểu diễn dưới dạng JSON |
|---|
{ "start": integer, "end": integer } |
| Trường | |
|---|---|
start |
Vị trí bắt đầu của kết quả khớp trong đoạn mã. |
end |
Thời điểm kết thúc trận đấu trong đoạn trích. |
Metadata
siêu dữ liệu của một kết quả tìm kiếm phù hợp.
| Biểu diễn dưới dạng JSON |
|---|
{ "source": { object ( |
| Trường | |
|---|---|
source |
Nguồn có 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) của tài liệu hoặc đối tượng trong kết quả tìm kiếm. |
createTime |
Thời gian tạo chứng từ hoặc đối tượng này trong kết quả tìm kiếm. Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: |
updateTime |
Ngày sửa đổi gần đây nhất của đối tượng trong kết quả tìm kiếm. Nếu bạn không đặt giá trị này trong mặt hàng, thì giá trị được trả về ở đây sẽ là giá trị trống. Khi Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. 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 chung có tên. |
displayOptions |
các lựa chọn chỉ định cách hiển thị kết quả tìm kiếm có 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 ( |
| Trường | |
|---|---|
objectTypeLabel |
Nhãn hiển thị cho đối tượng. |
metalines[] |
Nội dung metalines sẽ xuất hiện cùng với kết quả. |
ResultDisplayMetadata.ResultDisplayLine
Tập hợp các trường tạo nên một dòng hiển thị
| Biểu diễn dưới dạng JSON |
|---|
{
"fields": [
{
object ( |
| Trường | |
|---|---|
fields[] |
|
ResultDisplayMetadata.ResultDisplayField
Hiển thị các trường cho kết quả query.search
| Biểu diễn dưới dạng JSON |
|---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
| Trường | |
|---|---|
label |
Nhãn hiển thị của cơ sở lưu trú. |
operatorName |
Tên người vận hành của cơ sở lưu trú. |
property |
Cặp tên-giá trị cho thuộc tính. |
ResultDebugInfo
Thông tin gỡ lỗi về kết quả.
| Biểu diễn dưới dạng JSON |
|---|
{ "formattedDebugInfo": string } |
| 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ề trong yêu cầu tìm kiếm.
| Biểu diễn dưới dạng JSON |
|---|
{ // Union field |
| Trường | |
|---|---|
Trường nhóm
|
|
person |
Hình ảnh một người |
SpellResult
| Biểu diễn dưới dạng JSON |
|---|
{ "suggestedQuery": string, "suggestionType": enum ( |
| Trường | |
|---|---|
suggestedQuery |
Cách viết chính tả được đề xuất của cụm từ tìm kiếm. |
suggestionType |
đề xuất được kích hoạt cho cụm từ tìm kiếm hiện tại. |
suggestedQueryHtml |
HTML đã được dọn dẹp, đại diện cho cụm từ tìm kiếm đã được kiểm tra chính tả và có thể dùng trong giao diện người dùng. Thường thì điều này có các thẻ dành riêng cho ngôn ngữ để đánh dấu các phần của cụm từ tìm kiếm đã được kiểm tra chính tả. |
SpellResult.SuggestionType
Loại đề xuất được kích hoạt cho cụm từ tìm kiếm.
| Enum | |
|---|---|
SUGGESTION_TYPE_UNSPECIFIED |
Loại kiểm tra chính tả mặc định |
NON_EMPTY_RESULTS_SPELL_SUGGESTION |
Đề xuất chính tả không có kết quả nào thay đổi. Kết quả vẫn xuất hiện cho cụm từ tìm kiếm ban đầu (có kết quả khác 0) cùng với một đề xuất về lỗi chính tả có kết quả. |
ZERO_RESULTS_FULL_PAGE_REPLACEMENT |
Đề xuất chính tả được kích hoạt khi cụm từ tìm kiếm ban đầu không có kết quả. Khi truy vấn ban đầu không có kết quả và đề xuất chính tả có kết quả, chúng tôi sẽ kích hoạt kết quả cho truy vấn đã được sửa lỗi chính tả. |
SafeHtmlProto
QUAN TRỌNG: Không an toàn khi chấp nhận thông báo này từ một nguồn không đáng tin cậy, vì kẻ tấn công có thể dễ dàng giả mạo các thông báo được chuyển đổi tuần tự không đáp ứng hợp đồng an toàn của loại này – ví dụ: thông báo đó có thể chứa tập lệnh do kẻ tấn công kiểm soát. Một hệ thống nhận SafeHtmlProto sẽ ngầm tin tưởng nhà sản xuất SafeHtmlProto. Vì vậy, bạn thường có thể trả về thông báo này trong các phản hồi RPC, nhưng thường không an toàn khi chấp nhận thông báo này trong các yêu cầu RPC.
| Biểu diễn dưới dạng JSON |
|---|
{ "privateDoNotAccessOrElseSafeHtmlWrappedValue": string } |
| Trường | |
|---|---|
privateDoNotAccessOrElseSafeHtmlWrappedValue |
QUAN TRỌNG: Không bao giờ đặt hoặc đọc trường này, ngay cả trong các thử nghiệm, vì đây là trường riêng tư. Hãy xem tài liệu ở đầu tệp .proto để biết các gói ngôn ngữ lập trình dùng để tạo hoặc đọc thông báo này. |
FacetResult
Phản hồi khía cạnh dành riêng cho nguồn
| Biểu diễn dưới dạng JSON |
|---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
| Trường | |
|---|---|
sourceName |
Tên nguồn mà kết quả khía cạnh được trả về. Sẽ không trống. |
objectType |
Loại đối tượng mà kết quả của khía cạnh được trả về. Có thể để trống. |
operatorName |
Tên của toán tử được chọn để phân nhóm. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBuckets cho các giá trị trong phản hồi chứa ít nhất một kết quả có bộ lọc tương ứng. |
FacetBucket
Nhóm 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 tục, tuỳ thuộc vào loại nhóm trường. 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 ( |
| Trường | |
|---|---|
count |
Số lượng kết quả khớp với giá trị của bộ chứa. Số lượt tìm kiếm chỉ được trả về khi đảm bảo được độ chính xác của số lượt tìm kiếm. Cloud Search không đảm bảo số lượng khía cạnh cho bất kỳ cụm từ tìm kiếm nào và số lượng khía cạnh có thể chỉ xuất hiện không liên tục, ngay cả đối với các cụm từ tìm kiếm giống hệt nhau. Đừng tạo các phần phụ thuộc vào sự tồn tại của số lượng khía cạnh; thay vào đó, hãy sử dụng tỷ lệ phần trăm số lượng khía cạnh luôn được trả về. |
percentage |
Tỷ lệ phần trăm kết quả khớp với giá trị của nhóm. Giá trị được trả về nằm trong khoảng (0-100] và được làm tròn xuống thành số nguyên nếu là số phân số. Nếu giá trị không được trả về một cách rõ ràng, thì giá trị đó sẽ biểu thị một 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ả các lượt tìm kiếm, nhưng chỉ là số liệu ước tính. Vì các tỷ lệ phần trăm luôn được trả về, nên bạn cần hiển thị tỷ lệ phần trăm thay vì số lượng. |
filter |
Bộ lọc sẽ được truyền vào yêu cầu tìm kiếm nếu bạn chọn nhóm tương ứng. |
Trường nhóm bucket_value. Phạm vi hoặc giá trị của nhóm được phân loại bucket_value chỉ có thể là một trong những giá trị sau: |
|
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 |
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 ( |
| 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 ( |
| 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 ( |
| 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ả theo nguồn.
| Biểu diễn dưới dạng JSON |
|---|
{ "source": { object ( |
| Trường | |
|---|---|
source |
Nguồn mà thông tin về số lượng kết quả được liên kết. |
hasMoreResults |
Nguồn này có thêm kết quả tìm kiếm hay không. |
Trường nhóm
|
|
resultCountEstimate |
Số lượng 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. |