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 công khai dành cho nhà phát triển 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 đảm bảo rằng bạn đã bật API và tạo khoá API Developer Knowledge. Sau đó, hãy lưu khoá vào một biến môi trường:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Lưu ý: Nếu bạn cần câu trả lời được tổng hợp bằng ngôn ngữ tự nhiên dựa trên tài liệu thay vì các đoạn trích thô, hãy xem phần Trả lời câu hỏi bằng tính năng tạo câu trả lời có căn cứ.

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 các tài liệu trùng khớp, cùng với một parent tham chiếu 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":

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 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 số mức độ liên quan của đoạn văn với cụ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:

• pageSize (số nguyên): chỉ định số lượng kết quả tối đa cần trả về cho 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 ép buộc thành 100.
• pageToken (chuỗi): chỉ định mã thông báo nhận được trong một phản hồi trước đó để tìm nạp trang kết quả tiếp theo.

Yêu cầu trang đầu tiên

Để đặt kích thước trang, 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

Truyền giá trị của nextPageToken vào tham số pageToken trong yêu cầu tiếp theo của bạn:

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ị bỏ qua trong phản hồi.

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

Sử dụng tham số filter để á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 từng khối.

Biểu thức filter 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. Chúng tôi 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 -).

Ghi chú: OR có mức độ ưu tiên cao hơn AND. Sử dụng dấu ngoặc đơn (...) để nhóm rõ ràng nhằm đảm bảo các điều kiện được đánh giá theo thứ tự bạn muốn.

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 gọi API REST bằng curl, hãy nhớ mã hoá URL tham số bộ lọc hoặc sử dụng --data-urlencode.

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"

curl yêu cầu:

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"

curl yêu cầu:

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:

content_length_bytes < 5000

curl yêu cầu:

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"

curl yêu cầu:

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"

curl yêu cầu:

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 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.

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

Khi tham chiếu đến 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 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). Hãy sử dụng định dạng này cho trường uri khi tạo biểu thức filter (ví dụ: uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Ví dụ sau đây truy xuất một tài liệu theo tên tài nguyên:

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.

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. Điều 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 chứa danh sách các tài nguyên Document được yêu cầu 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ể 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

Tham số view kiểm soát những trường được điền sẵn trong thông báo Document.

Enum DocumentView hỗ trợ các giá trị sau:

• DOCUMENT_VIEW_BASIC: chỉ trả về các trường siêu dữ liệu cơ bản (name, uri, data_source, title, description, update_time và view). Trường content sẽ bị bỏ qua.
• 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 GetDocument và BatchGetDocuments.
• DOCUMENT_VIEW_FULL: trả về tất cả các trường của tài liệu.

Để chỉ truy xuất siêu dữ liệu của tài liệu mà không tải nội dung Markdown lớn xuống, hãy đặt view=DOCUMENT_VIEW_BASIC:

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

Cách 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

• Xem phần Trả lời các câu hỏi bằng tính năng tạo câu trả lời dựa trên thông tin thực tế.
• Khám phá cách sử dụng thư viện ứng dụng trong Python, Node.js, Go hoặc Java.
• Duyệt qua 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 đối với hạn mức và giới hạn tốc độ API.