Method: query.search

API Truy vấn Cloud Search cung cấp phương thức tìm kiếm, phương thức này sẽ 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ừ 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 của API truy vấn; để sử dụng tài khoản dịch vụ nhằm 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 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 phần Dùng toán tử để thu hẹp phạm vi tìm kiếm
pageSize

integer

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 bạn 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 dùng để truy vấn. Nếu 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[]

object (FacetOptions)
sortOptions

object (SortOptions)

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

object (QueryInterpretationOptions)

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

object (ContextAttribute)

Thuộc tính ngữ 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 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[]

object (SearchResult)

Kết quả của 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)

Cách viết chính tả đề xuất cho truy vấn.
facetResults[]

object (FacetResult)

Kết quả lặp lại theo phương diện.
hasMoreResults

boolean

Liệu có kết quả tìm kiếm nào khác khớ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 lỗi về phản hồi.
resultCounts

object (ResultCounts)

Mở rộng thông tin về số lượng kết quả.

Trường hợp hợp nhất 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. Bỏ qua nếu các nguồn được xác định trước có trong tập hợp 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ì số liệu 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ừ, chẳng hạn như "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 riêng biệt cần đánh giá quá lớn để tính toán trong độ trễ hợp lý.

Trong trường hợp hiếm gặp khi hệ thống không thể tìm kiếm trong tất 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 loại sau:
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 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

các tuỳ chọn để 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

Cờ để tắt tính năng diễn giải truy vấn bằng ngôn ngữ tự nhiên (NL). 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 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ính năng tối ưu hoá nội bộ như diễn giải cụm từ tìm kiếm 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 cả từ đồng nghĩa tuỳ chỉnh. Tính năng diễn giải Nl sẽ bị tắt nếu một trong hai cờ này là đúng.
disableSupplementalResults

boolean

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 được đặ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

Nội dung diễn giải cụm từ tìm kiếm được dùng trong kết quả tìm kiếm. Ví dụ: các cụm từ tìm kiếm có ý định bằng ngôn ngữ tự nhiên như "email from john" (email của john) sẽ được diễn giải 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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Lý do diễn giải truy vấn. Trường này sẽ không có giá trị UNSPECIFIED nếu loại bản dịch không phải là NONE.

QueryInterpretation.InterpretationType

Enum
NONE Hệ thống không sử dụng bản dịch ngôn ngữ tự nhiên cũng như 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ừ 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ừ 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 sẽ được 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 Hệ thống sẽ diễn giải cụm từ tìm kiếm bằng ngôn ngữ tự nhiên để tìm nạp kết quả tìm kiếm.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Mức độ 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 truy vấn một cách có chọn lọc 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. Truy vấn đượ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.

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 chứa lệnh chuyển hướng của Google đến mục thực tế. URL này đã được ký và không được thay đổi.
snippet

object (Snippet)

Chuỗi nối tất cả các đoạn mã (bản 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 cụm, hãy cung cấp danh sách kết quả được cụm. Sẽ chỉ có một cấp kết quả được nhóm lại. Nếu bạn chưa bật tính năng cụm từ cho nguồn hiện tại, thì 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 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 cần được huỷ thoát trước khi hiển thị.
matchRanges[]

object (MatchRange)

Các dải ô được so 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

integer

Vị trí bắt đầu của nội dung khớp trong đoạn mã.
end

integer

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

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 (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) của 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 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, có độ phân giải nano giây và tối đa 9 chữ số thập phân. 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 nhất của đố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ề tại đây sẽ trống. Khi updateTime được dùng để tính độ mới và không được đặt, giá trị này sẽ mặc định là 2 năm kể từ thời điểm hiện tại.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

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ê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ẽ hiển thị 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 (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Trường
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

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

string

Nhãn hiển thị của cơ sở lưu trú.
operatorName

string

Tên của nhà vận hành cơ sở lưu trú.
property

object (NamedProperty)

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

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 cho một người

SpellResult

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

string

Cách viết chính tả được đề xuất của truy vấn.

FacetResult

Phản hồi theo phương diện dành riêng cho 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ả phương diện. Không được để trống.
objectType

string

Loại đối tượng mà kết quả của phương diện được trả về. Có thể để trống.
operatorName

string

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

object (FacetBucket)

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

Một nhóm trong một phương diện là đơn vị hoạt động cơ bản. Một nhóm có thể bao gồm một giá trị hoặc một dải giá trị liền kề, 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ố kết quả khớp với giá trị nhóm. Số liệu chỉ được trả về cho các lượt tìm kiếm khi đảm bảo tính chính xác của số liệu. Cloud Search không đảm bảo số lượng phương diện cho bất kỳ cụm từ tìm kiếm nào và số lượng phương diện 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. Không tạo các phần phụ thuộc dựa trên sự tồn tại của số lượng phương diện; thay vào đó, hãy sử dụng tỷ lệ phần trăm số lượng phương diện 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ị được trả về nằm trong khoảng (0-100] và được làm tròn xuống số nguyên nếu là số thập phân. Nếu không được trả về một cách rõ ràng, giá trị này 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 cụm từ tìm kiếm, nhưng đây chỉ là số liệu ước tính. Vì tỷ lệ phần trăm luôn được trả về, nên bạn nên hiển thị tỷ lệ phần trăm thay vì số lượng.
filter

object (Filter)

Bộ lọc sẽ được truyền trong yêu cầu tìm kiếm nếu bạn chọn bộ chứa tương ứng.
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 lỗi về phản hồi.

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

object (ErrorMessage)

ErrorMessage

Thông báo lỗi cho 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ố lượng kết quả

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

object (SourceResultCount)

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 (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 nào cho nguồn này không.

Trường hợp hợp nhất result_count.

result_count chỉ có thể là một trong những loại sau:
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.