Package google.developers.knowledge.v1alpha

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 công việc của riêng bạn.

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 thông thường là trước tiên sử dụng DeveloperKnowledge.SearchDocumentChunks để tìm các đoạn tài liệu có liên quan dựa trên một truy vấn, sau đó sử dụng DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments với tên tài nguyên tài liệu (chẳng hạn như DocumentChunk.parent hoặc documents/{uri_without_scheme}) để tìm nạp toàn bộ nội dung của các 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.

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

Trả lời một câu hỏi bằng cách sử dụng tính năng tạo câu trả lời dựa trên dữ liệu thực tế.

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

Để biết thêm thông tin, hãy xem OAuth 2.0 Overview.
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/developerprofiles.readonly
  • 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 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/developerprofiles.readonly
  • 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/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

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

Trả lời

Câu trả lời cho một câu hỏi.

Trường
answer_text

string

Chứa nội dung của câu trả lời.
citations[]

AnswerCitation

Chỉ có đầu ra. Chứa các trích dẫn cho câu trả lời.
references[]

AnswerReference

Chỉ có đầu ra. Chứa tài liệu tham khảo cho câu trả lời.

AnswerCitation

Thông tin trích dẫn cho một phân đoạn.

Trường
start_index

int32

Chỉ có đầu ra. Cho biết điểm bắt đầu của phân đoạn, được đo bằng byte (UTF-8 unicode), bao gồm cả điểm bắt đầu. Nếu có các ký tự nhiều byte, chẳng hạn như ký tự không phải ASCII, thì số đo chỉ mục sẽ dài hơn độ dài chuỗi.
end_index

int32

Chỉ có đầu ra. Cho biết điểm kết thúc của phân đoạn, được đo bằng byte (Unicode UTF-8), không bao gồm. Nếu có các ký tự nhiều byte, chẳng hạn như ký tự không phải ASCII, thì số đo chỉ mục sẽ dài hơn độ dài chuỗi.
sources[]

CitationSource

Chỉ có đầu ra. Chứa các nguồn trích dẫn cho phân đoạn được ghi nhận tác giả.

AnswerReference

Đại diện cho một tệp đối chiếu đến một nguồn.

Trường
Trường nhóm content. Chứa nội dung của tệp đối chiếu. content chỉ có thể là một trong những trạng thái sau:
document_reference

DocumentReference

Chỉ có đầu ra. Tài liệu tham khảo.

CitationSource

Nguồn trích dẫn.

Trường
reference_index

int32

Chỉ có đầu ra. Chứa chỉ mục của Answer.AnswerReference trong trường lặp lại references.

DocumentReference

Đại diện cho một tệp đối chiếu đến một tài liệu.

Trường
document_chunk

DocumentChunk

Chỉ có đầu ra. Chứa đoạn tài liệu. Trường document_chunk.id chưa được đặt và sẽ để trống.

AnswerQueryRequest

Thông báo yêu cầu cho DeveloperKnowledge.AnswerQuery.

Trường
query

string

Bắt buộc. Câu hỏi cần trả lời.
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 dùng để xác minh câu trả lời. 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.

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

  • content_length_bytes (SỐ NGUYÊN): Độ dài của trường Document.content tính bằng byte.
  • 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 dữ liệu.
  • update_time (TIMESTAMP): Dấu thời gian của lần gần nhất tài liệu được cập nhật đáng kể. Bản cập nhật có ý nghĩa là bản cập nhật thay đổi nội dung hoặc siêu dữ liệu markdown của tài liệu.
  • uri (CHUỖI): URI của tài liệu, ví dụ: https://docs.cloud.google.com/bigquery/docs/tables.

Các trường INTEGER hỗ trợ toán tử =, <, <=, > và >=.

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. Không hỗ trợ so khớp một phần, so khớp tiền tố và so khớp biểu thức chính quy.

Trường TIMESTAMP hỗ trợ các 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 ưu tiên rõ ràng.

Ví dụ:

  • Lọc theo Document.content_length_bytes: content_length_bytes < 50000
  • 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.

AnswerQueryResponse

Tin nhắn phản hồi cho DeveloperKnowledge.AnswerQuery.

Trường
answer

Answer

Câu trả lời cho câu hỏi.

BatchGetDocumentsRequest

Thông báo yêu cầu cho DeveloperKnowledge.BatchGetDocuments.

Trường
names[]

string

Bắt buộc. Chỉ định tên của 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ô. Tài liệu được trả về theo cùng thứ tự với names trong yêu cầu.

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

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

DocumentView

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

BatchGetDocumentsResponse

Tin nhắn 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 đại diện cho một trang tài liệu trong kho Kiến thức dành cho nhà phát triển, chẳng hạn như trang tại https://docs.cloud.google.com/storage/docs/creating-buckets.

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ư https://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. Nguồn dữ liệu mẫ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. Cho biết dấu thời gian của lần gần nhất mà nội dung hoặc siêu dữ liệu của tài liệu được cập nhật.
view

DocumentView

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

int32

Chỉ có đầu ra. Độ dài của trường content tính bằng byte.

DocumentChunk

DocumentChunk đại diện cho một phần nội dung của Document trong kho văn bản DeveloperKnowledge. Để 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ã đoạn là duy nhất trong một tài liệu, nhưng không phải là duy nhất trên toàn cầu trong các tài liệu. Mã phân đoạn 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 lấy từ đó. DocumentView của tin nhắn Document này sẽ được đặt thành DOCUMENT_VIEW_BASIC. Trường này được đưa vào đây để thuận tiện cho ứng dụ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, ứng dụng khách nên sử dụng DeveloperKnowledge.GetDocument hoặc DeveloperKnowledge.BatchGetDocuments để tìm nạp toàn bộ nội dung tài liệu.
relevance_score

double

Chỉ có đầu ra. Biểu thị điểm mức độ liên quan của đoạn văn bản với cụm từ tìm kiếm. Điểm càng cao thì mức độ liên quan của đoạn càng cao. Điểm số nằm trong khoảng [0,0, 1,0].

DocumentView

Chỉ định những trường 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
  • content_length_bytes

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

Thông báo yêu cầu cho 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

Tên 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.
view

DocumentView

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

SearchDocumentChunksRequest

Thông báo yêu cầu cho 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 bộ chứa Cloud Storage?". Cụm từ tìm kiếm 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.
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 được chỉ định, hệ thống sẽ trả về tối đa 5 kết quả.

Giá trị tối đa là 100; các giá trị trên 100 sẽ được chuyển thành 100.
page_token

string

Không bắt buộc. Chứa mã thông báo trang, nhận được từ lệnh gọi SearchDocumentChunks trước đó. Cung cấp mã 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:

  • content_length_bytes (SỐ NGUYÊN): Độ dài của trường Document.content tính bằng byte.
  • 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 dữ liệu.
  • update_time (TIMESTAMP): Dấu thời gian của lần gần nhất tài liệu được cập nhật đáng kể. Bản cập nhật có ý nghĩa là bản cập nhật thay đổi nội dung hoặc siêu dữ liệu markdown của tài liệu.
  • uri (CHUỖI): URI của tài liệu, ví dụ: https://docs.cloud.google.com/bigquery/docs/tables.

Các trường INTEGER hỗ trợ toán tử =, <, <=, > và >=.

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. Không hỗ trợ so khớp một phần, so khớp tiền tố và so khớp biểu thức chính quy.

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

Lưu ý: Tên trường phải ở định dạng snake_case (ví dụ: data_source). Giá trị ở bên phải của biểu thức bộ lọc phải là giá trị cố định kiểu chuỗi được đặt trong dấu ngoặc kép (ví dụ: "docs.cloud.google.com").

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 ưu tiên rõ ràng.

Ví dụ:

  • Lọc theo Document.content_length_bytes: content_length_bytes < 50000
  • 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

Tin nhắn phản hồi cho DeveloperKnowledge.SearchDocumentChunks.

Trường
results[]

DocumentChunk

Chứa kết quả tìm kiếm cho cụm từ tìm kiếm đã cho. Mỗi DocumentChunk trong danh sách này chứa một trích đ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

Cung cấp 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 trường này bị bỏ qua, thì sẽ không có trang tiếp theo.