快速入門導覽課程：搭配使用 gcloud CLI 與 Developer Knowledge API

本快速入門導覽課程說明如何使用 Google Cloud CLI，透過 Developer Knowledge API 回答查詢、搜尋及擷取開發人員說明文件。

事前準備

開始透過 gcloud CLI 使用 Developer Knowledge API 前，請先完成下列步驟。

安裝及設定 gcloud CLI

如要安裝及設定 gcloud CLI，請完成下列步驟：

  1. 如果尚未安裝 gcloud CLI，請安裝 gcloud CLI。

  2. 執行 gcloud components update 指令，確認您使用的是最新版本：

    gcloud components update

  3. 執行 gcloud auth login 指令，登入 Google Cloud 帳戶：

    gcloud auth login

  4. 執行 gcloud config set 指令，設定有效的 Google Cloud 專案：

    gcloud config set project PROJECT_ID

    將 PROJECT_ID 替換為 Google Cloud 專案 ID。

啟用 API

如要啟用 Developer Knowledge API，請完成下列步驟：

  1. 執行 gcloud services enable 指令，在 Google Cloud 雲端專案中啟用 Developer Knowledge API：

    gcloud services enable developerknowledge.googleapis.com

    您不需要特定的 Identity and Access Management (IAM) 角色，即可啟用或使用 API。

  2. 執行 gcloud services list 指令，確認專案已啟用 API：

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

    輸出內容會列出 API 名稱和標題：

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

根據文件生成答案

gcloud developer-knowledge answer-query 指令 可讓您詢問 Google 產品相關問題，並直接以自然語言獲得解答。這項指令會從官方文件來源提取資訊，並提供所參考頁面的引文。

如要提問並生成答案，請完成下列步驟：

  1. 執行下列指令，詢問如何建立 Cloud Storage bucket：

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

  2. 確認指令會以 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

    輸出內容中的 answer 物件包含下列欄位：

    • answerText：系統根據查詢內容生成的自然語言答案。
    • citations：answerText 中的位元組偏移範圍 startIndex 和 endIndex，會透過 referenceIndex 對應至 references 中的支援項目。
    • references：用於生成答案的來源文件區塊和中繼資料，包括 document 和 parent。

搜尋文件區塊

如要在 Google 開發人員說明文件中尋找特定文字片段，而非生成的回覆，請使用 gcloud developer-knowledge documents search-chunks 指令。這項指令會掃描文件集，並傳回相符的內容區塊，以及父項文件的資源名稱。

如要搜尋文件區塊，請完成下列步驟：

  1. 執行下列指令，搜尋有關建立 Cloud Storage bucket 的文件：

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

  2. 確認指令會以 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

    輸出內容中的每個區塊都包含下列欄位：

    • content：說明文件中相符的文字片段。
    • document：來源文件的中繼資料，包括 title、description、uri、dataSource 和 updateTime。
    • id：文件內區塊的 ID。
    • parent：父項文件的資源名稱。您可以將這個值傳遞至 describe 指令，以擷取完整文件。
    • relevanceScore：區塊與搜尋查詢的相關分數。

擷取文件

找到相關的文件區塊後，請使用這些搜尋結果中的 parent 欄位，擷取文件的完整 Markdown 內容。

執行 gcloud developer-knowledge documents describe 指令，並提供文件的資源名稱。舉例來說，如要擷取建立 Cloud Storage bucket 的文件，請完成下列步驟：

  1. 執行下列指令：

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

  2. 確認指令會傳回文件的中繼資料和完整 Markdown 內容：

    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

    輸出內容包含下列欄位：

    • content：文件的完整 Markdown 文字。
    • contentLengthBytes：文件內容的總大小 (以位元組為單位)。
    • dataSource：代管文件的說明文件網域。
    • description：文件簡短摘要。
    • name：文件的專屬資源名稱。
    • title：文件標題。
    • updateTime：文件上次更新的時間戳記。
    • uri：說明文件頁面的公開網址。
    • view：傳回的文件檢視畫面 (DOCUMENT_VIEW_CONTENT、DOCUMENT_VIEW_BASIC 或 DOCUMENT_VIEW_FULL)。

後續步驟