Краткое руководство по началу работы с Developer Knowledge API с помощью gcloud CLI

В этом кратком руководстве показано, как отвечать на запросы, а также искать и извлекать документацию для разработчиков с помощью Developer Knowledge API, используя Google Cloud CLI.

Подготовка

Прежде чем начать использовать Developer Knowledge API с интерфейсом командной строки gcloud, выполните следующие действия:

Как установить и настроить gcloud CLI

Чтобы установить и настроить gcloud CLI, выполните следующие действия:

  1. Если вы ещё не установили gcloud CLI, сделайте это.

  2. Выполните команду gcloud components update, чтобы убедиться, что у вас установлена последняя версия:

    gcloud components update

  3. Войдите в аккаунт Google Cloud, выполнив команду gcloud auth login:

    gcloud auth login

  4. Чтобы задать активный проект Google Cloud, выполните команду gcloud config set:

    gcloud config set project PROJECT_ID

    Замените PROJECT_ID идентификатором вашего облачного проекта Google Cloud.

Включение API

Чтобы включить Developer Knowledge API, выполните следующие действия:

  1. Включите Developer Knowledge API в своем облачном проекте Google Cloud, выполнив команду gcloud services enable:

    gcloud services enable developerknowledge.googleapis.com

    Чтобы включить или использовать API, не нужны определенные роли управления учетными данными и доступом (IAM).

  2. Убедитесь, что API включен для вашего проекта, выполнив команду gcloud services list:

    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, выполните следующую команду:

    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 – диапазоны смещения байтов startIndex и endIndex в answerText, которые сопоставляются с поддерживаемыми записями в references с помощью referenceIndex.
    • references – фрагменты исходной документации и метаданные, в том числе document и parent, которые использовались для создания ответа.

Поиск фрагментов документов

Чтобы найти в документации для разработчиков Google определенные фрагменты текста, а не сгенерированный ответ, используйте команду gcloud developer-knowledge documents search-chunks. Эта команда сканирует корпус документации и возвращает соответствующие фрагменты контента вместе с названиями ресурсов их родительских документов.

Чтобы найти фрагменты документа, выполните следующие действия:

  1. Чтобы найти документацию о создании сегментов Cloud Storage, выполните следующую команду:

    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 – идентификатор фрагмента в документе.
    • parent – название ресурса родительского документа. Вы можете передать это значение команде describe, чтобы получить полный документ.
    • relevanceScore – оценка релевантности фрагмента поисковому запросу.

Как найти документ

Найдя подходящий фрагмент документа, используйте поле parent из результатов поиска, чтобы получить полный контент документа в формате Markdown.

Выполните команду gcloud developer-knowledge documents describe, указав название ресурса документа. Например, чтобы найти документ о создании сегментов Cloud Storage, выполните следующие действия:

  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 – общедоступный URL страницы документации.
    • view – представление документа (DOCUMENT_VIEW_CONTENT, DOCUMENT_VIEW_BASIC или DOCUMENT_VIEW_FULL).

Дальнейшие действия