Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tìm kiếm và truy xuất tài liệu

Tài liệu này hướng dẫn bạn cách sử dụng Developer Knowledge API để tìm kiếm và truy xuất tài liệu dành cho nhà phát triển công khai của Google theo phương thức lập trình. Thay vì trích xuất trang web theo cách thủ công, API này giúp các ứng dụng của bạn tìm thấy các đoạn văn bản có liên quan hoặc tìm nạp toàn bộ tài liệu Markdown.

Trong tài liệu này, bạn sẽ thấy các ví dụ về những việc sau:

Tìm kiếm trong kho tài liệu.
Phân trang qua kết quả tìm kiếm.
Áp dụng các bộ lọc phức tạp cho nội dung tìm kiếm.
Truy xuất toàn bộ nội dung của tài liệu.
Tối ưu hoá tải trọng phản hồi để giảm độ trễ.

Trước khi bắt đầu, hãy thiết lập môi trường cho công cụ mà bạn muốn dùng:

gcloud

Cài đặt và định cấu hình gcloud CLI, đồng thời bật Developer Knowledge API.

REST

Bật API và tạo khoá Developer Knowledge API. Sau đó, hãy lưu khoá vào một biến môi trường:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Thay thế YOUR_API_KEY bằng khoá API Kiến thức dành cho nhà phát triển.

Tìm tài liệu

Sử dụng lệnh gcloud developer-knowledge documents search-chunks hoặc phương thức REST 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 các tài liệu khớp, cùng với một parenttài liệu tham khảo mà bạn có thể dùng để truy xuất toàn bộ nội dung của những tài liệu đó.

Ví dụ sau đây tìm kiếm các tài liệu khớp với "BigQuery":

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

Kết quả sẽ tương tự như sau:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

Mỗi kết quả trong danh sách results đều có:

parent: tên tài nguyên của tài liệu (ví dụ: documents/docs.cloud.google.com/bigquery/docs/introduction).
id: giá trị nhận dạng đoạn trong tài liệu (ví dụ: chunk_0).
content: đoạn văn bản khớp trong giấy tờ.
document: siêu dữ liệu về tài liệu nguồn, chẳng hạn như title, uri, dataSource và updateTime.
relevanceScore: điểm số mức độ liên quan của đoạn văn bản với cụm từ tìm kiếm, trong phạm vi [0.0, 1.0].

Để biết thêm thông tin về giản đồ phản hồi và tất cả các trường siêu dữ liệu có sẵn, hãy xem tài liệu tham khảo documents.searchDocumentChunks API.

Phân trang kết quả tìm kiếm

Khi một cụm từ tìm kiếm trả về nhiều kết quả trùng khớp, bạn có thể di chuyển qua tập kết quả bằng cách sử dụng các tham số phân trang:

--page-size (giao diện dòng lệnh gcloud) hoặc pageSize (số nguyên): chỉ định số lượng kết quả tối đa cần trả về trên mỗi trang. Nếu bạn không chỉ định, API sẽ mặc định trả về 5 kết quả. Giá trị tối đa được phép là 100; các giá trị lớn hơn 100 sẽ được chuyển thành 100.
--limit (giao diện dòng lệnh gcloud) hoặc pageToken (chuỗi): trong giao diện dòng lệnh gcloud, hãy dùng --limit để kiểm soát tổng số kết quả được trả về trên các trang. Trong các yêu cầu REST, hãy truyền giá trị pageToken nhận được trong một phản hồi trước đó để tìm nạp trang kết quả tiếp theo.

gcloud

Truyền cờ --page-size và --limit để kiểm soát số lượng kết quả trên mỗi trang và tổng số kết quả được trả về:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

Để yêu cầu trang đầu tiên, hãy truyền tham số pageSize trong yêu cầu của bạn:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

Nếu có thêm kết quả, phản hồi sẽ bao gồm một nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

Để truy xuất các trang tiếp theo, hãy truyền giá trị của nextPageToken vào tham số pageToken trong yêu cầu tiếp theo:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Khi bạn truy cập vào trang kết quả cuối cùng, nextPageToken sẽ bị loại khỏi phản hồi.

Lọc kết quả tìm kiếm

Sử dụng cờ --query-filter trong gcloud CLI hoặc tham số filter trong các yêu cầu REST để áp dụng một bộ lọc nghiêm ngặt cho kết quả tìm kiếm. Biểu thức bộ lọc được áp dụng cho siêu dữ liệu của tài liệu mẹ cho từng khối.

Biểu thức bộ lọc có giới hạn 500 ký tự.

Các trường được hỗ trợ

Bạn có thể lọc kết quả tìm kiếm bằng các trường sau của tài liệu mẹ:

content_length_bytes (số nguyên): độ dài của trường content trong tài liệu tính bằng byte.
data_source (chuỗi): miền nguồn của tài liệu, chẳng hạn như docs.cloud.google.com hoặc firebase.google.com. Hãy xem tài liệu tham khảo về kho ngữ liệu để biết tất cả các nguồn dữ liệu được hỗ trợ.
update_time (dấu thời gian): dấu thời gian khi tài liệu được cập nhật lần gần đây nhất. Giá trị phải sử dụng định dạng RFC 3339 (ví dụ: "2025-01-01T00:00:00Z").
uri (chuỗi): URI đầy đủ của tài liệu (ví dụ: https://docs.cloud.google.com/bigquery/docs/tables).

Các toán tử được hỗ trợ

Trình phân tích cú pháp biểu thức bộ lọc hỗ trợ nhiều toán tử, tuỳ thuộc vào kiểu dữ liệu của trường:

Trường chuỗi (data_source, uri): hỗ trợ = (bằng) và != (không bằng) để so khớp chuỗi chính xác. Không hỗ trợ các kết quả so khớp một phần, tiền tố và biểu thức chính quy.
Trường dấu thời gian (update_time): hỗ trợ =, <, <=, > và >=.
Trường số nguyên (content_length_bytes): hỗ trợ =, !=, <, <=, > và >=.
Toán tử logic: kết hợp các điều kiện bằng cách sử dụng AND, OR và NOT (hoặc -).

Ví dụ về bộ lọc

Các ví dụ sau đây minh hoạ cách tạo biểu thức bộ lọc. Khi sử dụng CLI gcloud, hãy truyền biểu thức vào cờ --query-filter. Khi gọi API REST bằng curl, hãy nhớ mã hoá URL tham số filter hoặc sử dụng --data-urlencode.

So khớp một nguồn dữ liệu

Hạn chế kết quả tìm kiếm đối với một miền tài liệu duy nhất:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

So khớp nhiều nguồn dữ liệu

Sử dụng OR để thêm tài liệu từ nhiều nguồn:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Lọc theo dấu thời gian

Sử dụng toán tử so sánh với dấu thời gian RFC 3339 để tìm nội dung được cập nhật sau một ngày cụ thể:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Lọc theo độ dài nội dung

Sử dụng toán tử so sánh với content_length_bytes để tìm chứng từ dựa trên kích thước byte:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Kết hợp nguồn dữ liệu, dấu thời gian và nhóm

Kết hợp AND, OR và dấu ngoặc đơn (...) để giới hạn kết quả ở những nguồn cụ thể được cập nhật sau một ngày nhất định:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Loại trừ nguồn dữ liệu

Sử dụng biểu tượng NOT hoặc != để loại trừ kết quả từ một nguồn cụ thể:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Truy xuất tài liệu

Sử dụng lệnh gcloud developer-knowledge documents describe hoặc phương thức documents.get REST để 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 theo tên tài nguyên:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

Phản hồi là một tài nguyên Document chứa siêu dữ liệu và toàn bộ nội dung Markdown trong trường content.

Tên tài nguyên so với URI

Khi tham chiếu các tài liệu trong Developer Knowledge API, hãy lưu ý sự khác biệt giữa tên tài nguyên và URI web:

Tên tài nguyên (parent, name): được định dạng là documents/{uri_without_scheme} (ví dụ: documents/docs.cloud.google.com/storage/docs/creating-buckets). Truyền giá này làm đối số vị trí trong gcloud developer-knowledge documents describe, tham số đường dẫn trong GetDocument hoặc trong tham số names của BatchGetDocuments.
URI trên web (uri): URL đầy đủ trên web, bao gồm cả lược đồ (ví dụ: https://docs.cloud.google.com/storage/docs/creating-buckets). Sử dụng định dạng này cho trường uri khi tạo biểu thức --query-filter hoặc filter (ví dụ: uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

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 20 tài liệu theo tên trong một lệnh gọi API duy nhất. Cách này hiệu quả hơn so với việc đưa ra 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/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

Phản hồi này chứa danh sách các tài nguyên Document được yêu cầu theo thứ tự mà bạn yêu cầu.

Tối ưu hoá tải trọng phản hồi

Nội dung tài liệu ở định dạng Markdown có thể có kích thước lớn. Nếu ứng dụng của bạn chỉ cần siêu dữ liệu (chẳng hạn như tiêu đề trang, URI hoặc dấu thời gian) hoặc các trường cụ thể, bạn có thể tối ưu hoá kích thước tải trọng để giảm băng thông và độ trễ.

Sử dụng chế độ xem tài liệu

Cờ --view trong gcloud CLI hoặc tham số view trong các yêu cầu REST kiểm soát những trường được điền sẵn trong thông báo Document.

Cờ --view và enum DocumentView hỗ trợ các giá trị sau:

--view=basic (gcloud CLI) hoặc DOCUMENT_VIEW_BASIC: chỉ trả về các trường siêu dữ liệu cơ bản (name, uri, dataSource, title, description, updateTime và view). Trường content sẽ bị bỏ qua.
--view=content (giao diện dòng lệnh gcloud) hoặc DOCUMENT_VIEW_CONTENT: trả về các trường siêu dữ liệu cùng với trường Markdown content. Đây là giá trị mặc định cho gcloud developer-knowledge documents describe, GetDocument và BatchGetDocuments.
--view=full (gcloud CLI) hoặc DOCUMENT_VIEW_FULL: trả về tất cả các trường tài liệu.

Để chỉ truy xuất siêu dữ liệu tài liệu mà không tải nội dung Markdown lớn xuống, hãy chỉ định chế độ xem tài liệu cơ bản:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Bạn cũng có thể dùng view=DOCUMENT_VIEW_BASIC với BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Sử dụng mặt nạ trường

Để giới hạn hơn nữa tải trọng phản hồi cho các trường cụ thể, hãy sử dụng tham số truy vấn fields (mặt nạ trường) của API Google tiêu chuẩn.

Lọc các trường trong `GetDocument`

Để chỉ truy xuất các trường title, uri và updateTime của một tài liệu:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Lọc các trường trong `BatchGetDocuments`

Cách chỉ truy xuất các trường cụ thể cho từng tài liệu trong một lô:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

Lọc các trường trong `SearchDocumentChunks`

Để chỉ trả về đoạn id và content, tài liệu mẹ title và uri, cũng như nextPageToken từ một cụm từ tìm kiếm:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

Xử lý lỗi

Developer Knowledge API trả về mã trạng thái HTTP tiêu chuẩn. Các ví dụ chức năng sau đây liên kết mã trạng thái HTTP và nguyên nhân của chúng trong Developer Knowledge API:

400 INVALID_ARGUMENT:
- Chuỗi biểu thức filter vượt quá 500 ký tự.
- Dấu thời gian update_time không hợp lệ (phải sử dụng định dạng RFC 3339).
- Có hơn 20 tên tài liệu được cung cấp trong một yêu cầu BatchGetDocuments.
401 UNAUTHENTICATED: yêu cầu thiếu khoá API hoặc sử dụng khoá không hợp lệ. Xem phần Xác thực.
404 NOT_FOUND: tên tài liệu được yêu cầu không tồn tại hoặc thuộc về một miền không có trong kho ngữ liệu.
429 RESOURCE_EXHAUSTED: dự án đã vượt quá hạn mức. Xem Hạn mức và giới hạn.

Bước tiếp theo

Tham khảo phần Tạo câu trả lời từ tài liệu.
Kết nối với máy chủ MCP Kiến thức dành cho nhà phát triển và cài đặt kỹ năng tác nhân retrieving-developer-knowledge để trợ giúp lập trình AI của bạn có thể tìm kiếm và đọc tài liệu chính thức.
Khám phá cách sử dụng thư viện ứng dụng trong Python, Node.js, Go hoặc Java.
Tìm hiểu cách sử dụng CLI gcloud.
Duyệt xem tài liệu tham khảo về ngữ liệu để xem tất cả các nguồn tài liệu được hỗ trợ.
Xem tài liệu tham khảo API REST để biết đầy đủ quy cách về phương thức.
Kiểm tra hạn mức và giới hạn để biết hạn mức và giới hạn tốc độ API.

Tìm kiếm và truy xuất tài liệu Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

gcloud

REST

Tìm tài liệu

gcloud

REST

Phân trang kết quả tìm kiếm

gcloud

REST

Lọc kết quả tìm kiếm

Các trường được hỗ trợ

Các toán tử được hỗ trợ

Ví dụ về bộ lọc

So khớp một nguồn dữ liệu

gcloud

REST

So khớp nhiều nguồn dữ liệu

gcloud

REST

Lọc theo dấu thời gian

gcloud

REST

Lọc theo độ dài nội dung

gcloud

REST

Kết hợp nguồn dữ liệu, dấu thời gian và nhóm

gcloud

REST

Loại trừ nguồn dữ liệu

gcloud

REST

Truy xuất tài liệu

gcloud

REST

Tên tài nguyên so với URI

Truy xuất nhiều tài liệu bằng BatchGetDocuments

Tối ưu hoá tải trọng phản hồi

Sử dụng chế độ xem tài liệu

gcloud

REST

Sử dụng mặt nạ trường

Lọc các trường trong GetDocument

Lọc các trường trong BatchGetDocuments

Lọc các trường trong SearchDocumentChunks

Xử lý lỗi

Bước tiếp theo

Tìm kiếm và truy xuất tài liệu

Truy xuất nhiều tài liệu bằng `BatchGetDocuments`

Lọc các trường trong `GetDocument`

Lọc các trường trong `BatchGetDocuments`

Lọc các trường trong `SearchDocumentChunks`