Hướng dẫn này cung cấp ví dụ về cách sử dụng các hàm của Developer Knowledge API: tìm kiếm tài liệu, truy xuất một tài liệu và truy xuất nhiều tài liệu theo lô.
Trước khi bắt đầu, hãy đảm bảo bạn đã bật API và tạo khoá API Kiến thức dành cho nhà phát triển, đồng thời lưu khoá vào một biến môi trường:
export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"
Tìm kiếm tài liệu bằng SearchDocumentChunks
Sử dụng phương thức documents.searchDocumentChunks để tìm các đoạn tài liệu khớp với một chuỗi truy vấn. Kết quả bao gồm các đoạn nội dung trong tài liệu và một tham chiếu parent mà bạn có thể dùng để truy xuất toàn bộ nội dung tài liệu.
Ví dụ sau đây tìm kiếm các tài liệu khớp với "BigQuery":
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"
Bạn có thể tinh chỉnh kết quả tìm kiếm bằng các tham số như pageSize để giới hạn số lượng kết quả trên mỗi trang và pageToken để truy xuất các trang tiếp theo.
Lọc kết quả tìm kiếm
Sử dụng tham số filter để áp dụng một bộ lọc nghiêm ngặt cho kết quả tìm kiếm. Bộ lọc này được áp dụng cho siêu dữ liệu của các tài liệu được liên kết với các khối kết quả tìm kiếm.
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.update_time(TIMESTAMP): Dấu thời gian cho lần cập nhật gần nhất 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 toán tử được hỗ trợ:
- Các trường STRING hỗ trợ
=(bằng) và!=(không bằng) để khớp chính xác toàn bộ chuỗi. - Các trường TIMESTAMP hỗ trợ
=,<,<=,>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 các toán tử logic AND, OR và NOT (hoặc -). Xin lưu ý rằng OR có mức độ ưu tiên cao hơn AND.
Ví dụ sau đây tìm kiếm các tài liệu khớp với "BigQuery" và giới hạn kết quả ở những tài liệu từ docs.cloud.google.com:
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"
Truy xuất tài liệu bằng GetDocument
Sử dụng phương thức documents.get để truy xuất toàn bộ nội dung của một tài liệu.
Ví dụ sau đây truy xuất một tài liệu có tên documents/DOCUMENT_ID:
curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"
Phản hồi là toàn bộ tài nguyên Document, bao gồm cả trường content.
Truy xuất nhiều tài liệu bằng BatchGetDocuments
Sử dụng phương thức documents.batchGet để truy xuất tối đa 100 tài liệu theo tên trong một lệnh gọi API. Phương thức này hiệu quả hơn so với việc thực hiện nhiều yêu cầu GetDocument.
Ví dụ sau đây truy xuất hai tài liệu theo tên:
curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"
Phản hồi chứa danh sách các tài nguyên Document được yêu cầu.