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 sẽ 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ì tự động thu thập thông tin trên các trang web, API này giúp ứ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 ở định dạng 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 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 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ụ bạn muốn dùng:

gcloud

Cài đặt và định cấu hình CLI gcloud, đồng thời bật API Kiến thức dành cho nhà phát triển.

REST

Bật API và tạo khoá API Kiến thức dành cho nhà phát triển. 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 kiếm tài liệu

Sử dụng gcloud developer-knowledge documents search-chunks lệnh hoặc documents.searchDocumentChunks phương thức REST để 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 tham chiếu parent mà bạn có thể dùng để truy xuất toàn bộ nội dung của các 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ư kết quả 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 bao gồm:

parent: tên tài nguyên của tài liệu (ví dụ: documents/docs.cloud.google.com/bigquery/docs/introduction).
id: mã 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 tài liệu.
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 mức độ liên quan của đoạ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ề lược đồ phản hồi và tất cả các trường siêu dữ liệu hiện có, hãy xem tài liệu tham khảo API documents.searchDocumentChunks.

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

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

--page-size (CLI 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 là 5 kết quả. Giá trị tối đa được phép là 100; các giá trị lớn hơn 100 sẽ bị ép thành 100.
--limit (CLI gcloud) hoặc pageToken (chuỗi): trong CLI 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 phản hồi trước đó để tìm nạp trang kết quả tiếp theo.

gcloud

Truyền các 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 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 đến trang kết quả cuối cùng, nextPageToken sẽ bị bỏ qua trong phản hồi.

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

Sử dụng cờ --query-filter trong CLI gcloud hoặc filter tham số trong các yêu cầu REST để áp dụng 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 mỗi đoạn.

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 tài liệu mẹ sau đây:

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. Xem tài liệu tham khảo về kho tài 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 gần đây nhất. Các 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 loại 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 chính xác 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 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:

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 để đưa các tài liệu từ nhiều nguồn vào:

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 tài liệu dựa trên kích thước byte của chúng:

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 (...) để hạn chế kết quả đối với các 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 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 REST 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 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 Document tài nguyên chứa siêu dữ liệu và toàn bộ nội dung ở định dạng Markdown trong trường content.

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

Khi tham chiếu đến 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á trị 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 web (uri): URL web đầy đủ 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 documents.batchGet phương thức để truy xuất tối đa 20 tài liệu theo tên trong một lệnh gọi API. 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 2 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 chứa danh sách các tài nguyên được yêu cầu Document theo thứ tự 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ể 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 CLI gcloud hoặc tham số view trong các yêu cầu REST kiểm soát những trường được điền trong Document thông báo.

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

--view=basic (CLI gcloud) 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 (CLI gcloud) hoặc DOCUMENT_VIEW_CONTENT: trả về các trường siêu dữ liệu cùng với trường content ở định dạng Markdown. Đây là giá trị mặc định cho gcloud developer-knowledge documents describe, GetDocument, và BatchGetDocuments.
--view=full (CLI gcloud) 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 cần tải nội dung lớn ở định dạng Markdown 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ể sử 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 thêm tải trọng phản hồi đối với các trường cụ thể, hãy sử dụng tham số truy vấn fields của API Google (mặt nạ trường) 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`

Để 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ề id và content của đoạn, title và uri của tài liệu mẹ và nextPageToken từ một lượ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

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

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 yêu cầu BatchGetDocuments.
401 UNAUTHENTICATED: yêu cầu thiếu khoá API hoặc mã thông báo Bearer hoặc sử dụng thông tin đăng nhập không hợp lệ. Tham khảo bài viết 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 tài liệu.
429 RESOURCE_EXHAUSTED: dự án đã vượt quá hạn mức. Xem bài viết Hạn mức và giới hạn.

Bước tiếp theo

Tham khảo bài viết 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 retrieving-developer-knowledge kỹ năng tác nhân để giúp trợ giúp lập trình AI tìm kiếm và đọc tài liệu chính thức.
Tìm hiểu 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 tài liệu tham khảo về kho tài 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 thông số kỹ thuật đầy đủ của phương thức.
Kiểm tra hạn mức và giới hạn đối với hạn mức và hạn ngạch 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 kiế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`