Method: query.search

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 (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Các trường
requestOptions

object (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

string

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

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 yêu cầu kết quả sau 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 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[]

object (FacetOptions)
sortOptions

object (SortOptions)

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)

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 (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.
}
Các 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 phần 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)

Cách viết 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

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

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)

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

Trường nhóm result_count. Tổng số kết quả trên tất cả các nguồn dữ liệu yêu cầu. Bị bỏ qua nếu các nguồn 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ì số lượng 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ư "số lượng kết quả chính xác" trong dấu ngoặc kép.

  • Khi số lượng ACL của 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 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. 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 cụm từ tìm kiếm này.
resultCountExact

string (int64 format)

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

boolean

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

boolean

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

boolean

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 (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Các trường
interpretedQuery

string

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

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 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 (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Các 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ặt hàng thực tế. URL này đã được ký và không nên thay đổi.
snippet

object (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

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

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

object (MatchRange)

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

integer

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

integer

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 (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Các trường
source

object (Source)

Nguồn được đặt tên của 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 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ụ: "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 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 updateTime được dùng để tính toán độ mới và không được thiết lập, 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, với độ phân giải nano giây và tối đa 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 đượ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

object (ResultDisplayMetadata)

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)
    }
  ]
}
Các trường
objectTypeLabel

string

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

object (ResultDisplayMetadata.ResultDisplayLine)

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 (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Các 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)
  }
}
Các trường
label

string

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

string

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

object (NamedProperty)

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

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

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

object (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

string

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 (FacetBucket)
    }
  ]
}
Các trường
sourceName

string

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

string

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

string

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

object (FacetBucket)

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 (Filter)
  },
  "value": {
    object (Value)
  }
}
Các 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 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

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

object (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

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
}
Các 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)
    }
  ]
}
Các trường
errorMessages[]

object (ErrorMessage)

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 (Source)
  },
  "errorMessage": string
}
Các 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)
    }
  ]
}
Các 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ả trên mỗi 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.
}
Các 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 nhóm result_count.

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

string (int64 format)

Số 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.