Package google.developers.knowledge.v1

Chỉ mục

DeveloperKnowledge

Developer Knowledge API cung cấp quyền truy cập có lập trình vào tài liệu công khai dành cho nhà phát triển của Google, cho phép bạn tích hợp cơ sở kiến thức này vào các ứng dụng và quy trình làm việc của riêng mình.

API này được thiết kế để trở thành nguồn chính tắc cho quyền truy cập có thể đọc được bằng máy vào tài liệu dành cho nhà phát triển của Google.

Một trường hợp sử dụng điển hình là trước tiên sử dụng DeveloperKnowledge.SearchDocumentChunks để tìm URI trang có liên quan dựa trên một truy vấn, sau đó sử dụng DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments để tìm nạp toàn bộ nội dung của kết quả hàng đầu.

Tất cả nội dung tài liệu đều được cung cấp ở định dạng Markdown.

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Truy xuất nhiều tài liệu, mỗi tài liệu có nội dung Markdown đầ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/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

Để biết thêm thông tin, hãy xem OAuth 2.0 Overview.
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Truy xuất một tài liệu duy nhất có nội dung Markdown đầ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/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

Để biết thêm thông tin, hãy xem OAuth 2.0 Overview.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

Tìm kiếm kiến thức dành cho nhà phát triển trong tài liệu dành cho nhà phát triển của Google. Trả về DocumentChunk dựa trên cụm từ tìm kiếm của người dùng. Có thể có nhiều đoạn từ cùng một Document. Để truy xuất toàn bộ tài liệu, hãy sử dụng DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments với DocumentChunk.parent được trả về trong SearchDocumentChunksResponse.results.

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/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

Để biết thêm thông tin, hãy xem OAuth 2.0 Overview.

BatchGetDocumentsRequest

Yêu cầu quyền truy cập vào thư từ DeveloperKnowledge.BatchGetDocuments.

Trường
names[]

string

Bắt buộc. Chỉ định tên của các tài liệu cần truy xuất. Bạn có thể truy xuất tối đa 20 tài liệu trong một lô. Các tài liệu được trả về theo cùng thứ tự như names trong yêu cầu.

Định dạng: documents/{uri_without_scheme} Ví dụ: documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

Không bắt buộc. Chỉ định DocumentView của tài liệu. Nếu bạn không chỉ định, DeveloperKnowledge.BatchGetDocuments sẽ mặc định là DOCUMENT_VIEW_CONTENT.

BatchGetDocumentsResponse

Thông báo phản hồi cho DeveloperKnowledge.BatchGetDocuments.

Trường
documents[]

Document

Chứa các giấy tờ được yêu cầu.

Tài liệu

Tài liệu là một phần nội dung trong kho kiến thức dành cho nhà phát triển.

Trường
name

string

Giá trị nhận dạng. Chứa tên tài nguyên của tài liệu. Định dạng: documents/{uri_without_scheme} Ví dụ: documents/docs.cloud.google.com/storage/docs/creating-buckets
uri

string

Chỉ có đầu ra. Cung cấp URI của nội dung, chẳng hạn như docs.cloud.google.com/storage/docs/creating-buckets.
content

string

Chỉ có đầu ra. Chứa toàn bộ nội dung của tài liệu ở định dạng Markdown.
description

string

Chỉ có đầu ra. Cung cấp nội dung mô tả về tài liệu.
data_source

string

Chỉ có đầu ra. Chỉ định nguồn dữ liệu của tài liệu. Ví dụ về nguồn dữ liệu: firebase.google.com
title

string

Chỉ có đầu ra. Cung cấp tiêu đề của tài liệu.
update_time

Timestamp

Chỉ có đầu ra. Biểu thị dấu thời gian khi nội dung hoặc siêu dữ liệu của tài liệu được cập nhật lần gần đây nhất.
view

DocumentView

Chỉ có đầu ra. Chỉ định DocumentView của tài liệu.

DocumentChunk

DocumentChunk biểu thị một phần nội dung từ Document trong tập hợp kiến thức của nhà phát triển. Để tìm nạp toàn bộ nội dung tài liệu, hãy truyền parent đến DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments.

Trường
parent

string

Chỉ có đầu ra. Chứa tên tài nguyên của tài liệu mà đoạn này thuộc về. Định dạng: documents/{uri_without_scheme} Ví dụ: documents/docs.cloud.google.com/storage/docs/creating-buckets
id

string

Chỉ có đầu ra. Chỉ định mã nhận dạng của đoạn này trong tài liệu. Mã nhận dạng đoạn là mã nhận dạng duy nhất trong một tài liệu, nhưng không phải là mã nhận dạng duy nhất trên toàn cầu giữa các tài liệu. Mã nhận dạng khối không ổn định và có thể thay đổi theo thời gian.
content

string

Chỉ có đầu ra. Chứa nội dung của đoạn tài liệu.
document

Document

Chỉ có đầu ra. Biểu thị siêu dữ liệu về Document mà đoạn này thuộc về. DocumentView của tin nhắn Document này sẽ được đặt thành DOCUMENT_VIEW_BASIC. Thao tác này được đưa vào đây để thuận tiện cho khách hàng, nhờ đó, khách hàng không cần gọi DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments nếu chỉ cần các trường siêu dữ liệu. Nếu không, các ứng dụng nên dùng DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments để tìm nạp nội dung đầy đủ của tài liệu.

DocumentView

Chỉ định những trường nào của Document được đưa vào.

Enum
DOCUMENT_VIEW_UNSPECIFIED Giá trị mặc định / chưa đặt. Hãy xem từng phương thức API để biết giá trị mặc định nếu bạn không chỉ định DocumentView.
DOCUMENT_VIEW_BASIC

Chỉ bao gồm các trường siêu dữ liệu cơ bản: – name – uri – data_source – title – description – update_time – view

Đây là chế độ xem mặc định cho DeveloperKnowledge.SearchDocumentChunks.
DOCUMENT_VIEW_FULL Bao gồm tất cả các trường Document.
DOCUMENT_VIEW_CONTENT

Bao gồm các trường DOCUMENT_VIEW_BASIC và trường content.

Đây là chế độ xem mặc định cho DeveloperKnowledge.GetDocument và DeveloperKnowledge.BatchGetDocuments.

GetDocumentRequest

Yêu cầu quyền truy cập vào thư từ DeveloperKnowledge.GetDocument.

Trường
name

string

Bắt buộc. Chỉ định tên của tài liệu cần truy xuất. Định dạng: documents/{uri_without_scheme} Ví dụ: documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

Không bắt buộc. Chỉ định DocumentView của tài liệu. Nếu bạn không chỉ định, DeveloperKnowledge.GetDocument sẽ mặc định là DOCUMENT_VIEW_CONTENT.

SearchDocumentChunksRequest

Yêu cầu quyền truy cập vào thư từ DeveloperKnowledge.SearchDocumentChunks.

Trường
query

string

Bắt buộc. Cung cấp chuỗi truy vấn thô do người dùng cung cấp, chẳng hạn như "Cách tạo một vùng lưu trữ Cloud Storage".
page_size

int32

Không bắt buộc. Chỉ định số lượng kết quả tối đa cần trả về. Dịch vụ có thể trả về ít hơn giá trị này.

Nếu không chỉ định, tối đa 5 kết quả sẽ được trả về.

Giá trị tối đa là 20; các giá trị lớn hơn 20 sẽ dẫn đến lỗi INVALID_ARGUMENT.
page_token

string

Không bắt buộc. Chứa một mã thông báo trang, nhận được từ lệnh gọi SearchDocumentChunks trước đó. Cung cấp thông tin này để truy xuất trang tiếp theo.
filter

string

Không bắt buộc. Áp dụng bộ lọc nghiêm ngặt cho kết quả tìm kiếm. Biểu thức này hỗ trợ một tập hợp con của cú pháp được mô tả tại https://google.aip.dev/160.

Mặc dù SearchDocumentChunks trả về DocumentChunk, nhưng bộ lọc được áp dụng cho các trường DocumentChunk.document.

Các trường được hỗ trợ để lọc:

  • data_source (STRING): Nguồn của tài liệu, ví dụ: docs.cloud.google.com. Hãy xem https://developers.google.com/knowledge/reference/corpus-reference để biết danh sách đầy đủ các nguồn dữ liệu trong kho ngữ liệu.
  • update_time (DẤU THỜI GIAN): Dấu thời gian cho biết lần cập nhật có ý nghĩa gần đây nhất của tài liệu. Bản cập nhật có ý nghĩa là bản cập nhật làm thay đổi nội dung markdown hoặc siêu dữ liệu của tài liệu.
  • uri (STRING): URI của tài liệu, ví dụ: https://docs.cloud.google.com/bigquery/docs/tables.

Các trường STRING hỗ trợ toán tử = (bằng) và != (không bằng) để khớp chính xác trên toàn bộ chuỗi. Chúng tôi không hỗ trợ các tiêu chí khớp một phần, khớp tiền tố và khớp biểu thức chính quy.

Các trường DẤU THỜI GIAN hỗ trợ toán tử =, <, <=, > và >=. Dấu thời gian phải ở định dạng RFC-3339, ví dụ: "2025-01-01T00:00:00Z".

Bạn có thể kết hợp các biểu thức bằng cách sử dụng toán tử logic AND, OR và NOT (hoặc -). OR có mức độ ưu tiên cao hơn AND. Sử dụng dấu ngoặc đơn để nhóm theo mức độ ưu tiên rõ ràng.

Ví dụ:

  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

Chuỗi filter không được vượt quá 500 ký tự; các giá trị dài hơn 500 ký tự sẽ dẫn đến lỗi INVALID_ARGUMENT.

SearchDocumentChunksResponse

Thông báo phản hồi cho DeveloperKnowledge.SearchDocumentChunks.

Trường
results[]

DocumentChunk

Chứa kết quả tìm kiếm cho truy vấn đã cho. Mỗi DocumentChunk trong danh sách này chứa một đoạn nội dung liên quan đến cụm từ tìm kiếm. Sử dụng trường DocumentChunk.parent của mỗi kết quả với DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments để truy xuất toàn bộ nội dung tài liệu.
next_page_token

string

Không bắt buộc. Cung cấp một mã thông báo có thể được gửi dưới dạng page_token để truy xuất trang tiếp theo. Nếu bạn bỏ qua trường này, thì sẽ không có trang tiếp theo.