Hướng dẫn bắt đầu nhanh: Sử dụng gcloud CLI với Developer Knowledge API

Hướng dẫn bắt đầu nhanh này hướng dẫn bạn cách trả lời các truy vấn cũng như tìm kiếm và truy xuất tài liệu dành cho nhà phát triển bằng Developer Knowledge API thông qua Google Cloud CLI.

Trước khi bắt đầu

Trước khi bắt đầu sử dụng Developer Knowledge API bằng gcloud CLI, hãy hoàn tất các bước sau.

Cài đặt và định cấu hình gcloud CLI

Để cài đặt và định cấu hình gcloud CLI, hãy hoàn tất các bước sau:

  1. Nếu bạn chưa cài đặt gcloud CLI, hãy cài đặt gcloud CLI.

  2. Chạy lệnh gcloud components update để đảm bảo bạn có phiên bản mới nhất:

    gcloud components update

  3. Đăng nhập vào tài khoản Google Cloud của bạn bằng cách chạy lệnh gcloud auth login:

    gcloud auth login

  4. Đặt dự án trên đám mây của Google Cloud đang hoạt động bằng cách chạy lệnh gcloud config set:

    gcloud config set project PROJECT_ID

    Thay thế PROJECT_ID bằng mã nhận dạng dự án Google Cloud của bạn.

Bật API

Để bật Developer Knowledge API, hãy hoàn tất các bước sau:

  1. Bật Developer Knowledge API trong dự án trên đám mây của bạn bằng cách chạy lệnh gcloud services enable:

    gcloud services enable developerknowledge.googleapis.com

    Bạn không cần có các vai trò Quản lý danh tính và quyền truy cập (IAM) cụ thể để bật hoặc sử dụng API.

  2. Xác minh rằng API đã được bật cho dự án của bạn bằng cách chạy lệnh gcloud services list:

    gcloud services list --enabled \
    --filter="name:developerknowledge.googleapis.com"

    Kết quả đầu ra liệt kê tên và tiêu đề API:

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

Tạo câu trả lời từ tài liệu

Lệnh gcloud developer-knowledge answer-query cho phép bạn đặt câu hỏi về các sản phẩm của Google và nhận câu trả lời trực tiếp bằng ngôn ngữ tự nhiên. Lệnh này lấy thông tin từ các nguồn tài liệu chính thức và cung cấp thông tin trích dẫn cho các trang được tham chiếu.

Để đặt câu hỏi và tạo câu trả lời, hãy hoàn tất các bước sau:

  1. Chạy lệnh sau để hỏi cách tạo một bộ chứa Cloud Storage:

    gcloud developer-knowledge answer-query \
    --query="How do I create a Cloud Storage bucket?"

  2. Xác nhận rằng lệnh này trả về câu trả lời được tạo và các tài liệu tham khảo nguồn ở định dạng YAML:

    answer:
  answerText: |-
    To create a Cloud Storage bucket, you can use the Google Cloud console,
    the gcloud CLI (`gcloud storage buckets create`), client libraries, or
    the REST API...
  citations:
  - endIndex: 158
    sources:
    - referenceIndex: 0
    startIndex: 0
  references:
  - documentReference:
      documentChunk:
        content: |-
          This document shows you how to create a Cloud Storage
          [bucket](https://docs.cloud.google.com/storage/docs/buckets)...
        document:
          dataSource: docs.cloud.google.com
          name: documents/docs.cloud.google.com/storage/docs/creating-buckets
          title: Create a bucket
          uri: https://docs.cloud.google.com/storage/docs/creating-buckets
        parent: documents/docs.cloud.google.com/storage/docs/creating-buckets

    Đối tượng answer trong đầu ra bao gồm các trường sau:

    • answerText: câu trả lời bằng ngôn ngữ tự nhiên được tạo cho câu hỏi của bạn.
    • citations: dải ô byte-offset, startIndex và endIndex, trong answerText ánh xạ đến các mục hỗ trợ trong references theo referenceIndex.
    • references: các đoạn tài liệu nguồn và siêu dữ liệu, bao gồm cả document và parent, được dùng để tạo câu trả lời.

Tìm kiếm các đoạn tài liệu

Để tìm các đoạn trích văn bản cụ thể trong tài liệu dành cho nhà phát triển của Google thay vì câu trả lời được tạo, hãy sử dụng lệnh gcloud developer-knowledge documents search-chunks. Lệnh này quét kho tài liệu và trả về các đoạn nội dung phù hợp cùng với tên tài nguyên của các tài liệu mẹ.

Để tìm các đoạn tài liệu, hãy hoàn tất các bước sau:

  1. Chạy lệnh sau để tìm tài liệu về cách tạo vùng chứa Cloud Storage:

    gcloud developer-knowledge documents search-chunks \
    --query="How do I create a Cloud Storage bucket?"

  2. Xác nhận rằng lệnh này trả về một danh sách các đoạn tài liệu khớp ở định dạng YAML:

    ---
content: |-
  This document shows you how to create a Cloud Storage
  [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise
  specified in your request, buckets are created in the
  [US multi-region](https://docs.cloud.google.com/storage/docs/locations)...
document:
  contentLengthBytes: 31842
  dataSource: docs.cloud.google.com
  description: World-wide storage and retrieval of data in Google Cloud.
  name: documents/docs.cloud.google.com/storage/docs/creating-buckets
  title: Create a bucket
  updateTime: '2026-09-10T20:05:41Z'
  uri: https://docs.cloud.google.com/storage/docs/creating-buckets
  view: DOCUMENT_VIEW_BASIC
id: c1
parent: documents/docs.cloud.google.com/storage/docs/creating-buckets
relevanceScore: 0.856608

    Mỗi đoạn trong đầu ra bao gồm các trường sau:

    • content: đoạn văn bản khớp từ tài liệu.
    • document: siêu dữ liệu về tài liệu nguồn, bao gồm title, description, uri, dataSource và updateTime.
    • id: giá trị nhận dạng của đoạn trong tài liệu.
    • parent: tên tài nguyên của tài liệu mẹ. Bạn có thể truyền giá trị này đến lệnh describe để truy xuất toàn bộ tài liệu.
    • relevanceScore: điểm số mức độ liên quan của đoạn văn với cụm từ tìm kiếm.

Truy xuất tài liệu

Sau khi bạn tìm thấy một đoạn tài liệu có liên quan, hãy sử dụng trường parent trong các kết quả tìm kiếm đó để tìm nạp nội dung Markdown hoàn chỉnh của tài liệu.

Chạy lệnh gcloud developer-knowledge documents describe bằng tên tài nguyên của tài liệu. Ví dụ: để truy xuất tài liệu về cách tạo vùng lưu trữ trên Cloud Storage, hãy hoàn tất các bước sau:

  1. Chạy lệnh sau:

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

  2. Xác nhận rằng lệnh này trả về siêu dữ liệu và nội dung Markdown đầy đủ của tài liệu:

    content: |
  This document shows you how to create a Cloud Storage [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise specified in your request, buckets are
  created in the [`US` multi-region](https://docs.cloud.google.com/storage/docs/locations)
  with a default storage class of [Standard storage](https://docs.cloud.google.com/storage/docs/storage-classes)
  and have a seven-day [soft delete](https://docs.cloud.google.com/storage/docs/soft-delete)
  retention duration...
contentLengthBytes: 31842
dataSource: docs.cloud.google.com
description: World-wide storage and retrieval of data in Google Cloud.
name: documents/docs.cloud.google.com/storage/docs/creating-buckets
title: Create a bucket
updateTime: '2026-09-10T20:05:41Z'
uri: https://docs.cloud.google.com/storage/docs/creating-buckets
view: DOCUMENT_VIEW_CONTENT

    Đầu ra bao gồm các trường sau:

    • content: toàn bộ văn bản Markdown của tài liệu.
    • contentLengthBytes: tổng kích thước của nội dung tài liệu tính bằng byte.
    • dataSource: miền tài liệu lưu trữ tài liệu.
    • description: bản tóm tắt ngắn gọn về giấy tờ.
    • name: tên tài nguyên duy nhất của tài liệu.
    • title: tiêu đề của tài liệu.
    • updateTime: dấu thời gian khi tài liệu được cập nhật lần gần đây nhất.
    • uri: URL công khai của trang tài liệu.
    • view: khung hiển thị tài liệu được trả về (DOCUMENT_VIEW_CONTENT, DOCUMENT_VIEW_BASIC hoặc DOCUMENT_VIEW_FULL).

Bước tiếp theo