Guida rapida: utilizza gcloud CLI con l'API Developer Knowledge

Questa guida rapida mostra come rispondere alle query e cercare e recuperare la documentazione per sviluppatori con l'API Developer Knowledge utilizzando Google Cloud CLI.

Prima di iniziare

Prima di iniziare a utilizzare l'API Developer Knowledge con gcloud CLI, completa i seguenti passaggi.

Installa e configura gcloud CLI

Per installare e configurare gcloud CLI, completa i seguenti passaggi:

  1. Se non hai installato gcloud CLI, installala.

  2. Esegui il comando gcloud components update per assicurarti di avere l'ultima versione:

    gcloud components update

  3. Accedi al tuo account Google Cloud eseguendo il comando gcloud auth login:

    gcloud auth login

  4. Imposta il progetto Google Cloud attivo eseguendo il comando gcloud config set:

    gcloud config set project PROJECT_ID

    Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud.

Abilita l'API

Per abilitare l'API Developer Knowledge, completa i seguenti passaggi:

  1. Attiva l'API Developer Knowledge nel tuo progetto Google Cloud eseguendo il comando gcloud services enable:

    gcloud services enable developerknowledge.googleapis.com

    Non sono necessari ruoli Identity and Access Management (IAM) specifici per attivare o utilizzare l'API.

  2. Verifica che l'API sia abilitata per il tuo progetto eseguendo il comando gcloud services list:

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

    L'output elenca il nome e il titolo dell'API:

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

Generare risposte dalla documentazione

Il comando gcloud developer-knowledge answer-query ti consente di porre domande sui prodotti Google e ricevere risposte dirette in linguaggio naturale. Il comando estrae le informazioni da fonti di documentazione ufficiali e fornisce citazioni delle pagine a cui viene fatto riferimento.

Per porre una domanda e generare una risposta, completa i seguenti passaggi:

  1. Esegui questo comando per chiedere come creare un bucket Cloud Storage:

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

  2. Verifica che il comando restituisca una risposta generata e riferimenti alle fonti in formato 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

    L'oggetto answer nell'output include i seguenti campi:

    • answerText: la risposta in linguaggio naturale generata per la tua query.
    • citations: intervalli di offset in byte, startIndex e endIndex, in answerText che vengono mappati alle voci di supporto in references da referenceIndex.
    • references: i blocchi e i metadati della documentazione di origine, inclusi document e parent, utilizzati per generare la risposta.

Cercare blocchi di documenti

Per trovare estratti di testo specifici nella documentazione per sviluppatori di Google anziché una risposta generata, utilizza il comando gcloud developer-knowledge documents search-chunks. Questo comando esegue la scansione del corpus della documentazione e restituisce i blocchi di contenuti corrispondenti insieme ai nomi delle risorse dei documenti principali.

Per cercare i blocchi di documenti, completa i seguenti passaggi:

  1. Esegui questo comando per cercare la documentazione sulla creazione di bucket Cloud Storage:

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

  2. Verifica che il comando restituisca un elenco di blocchi di documenti corrispondenti in formato 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

    Ogni blocco nell'output include i seguenti campi:

    • content: lo snippet di testo corrispondente della documentazione.
    • document: metadati sul documento di origine, inclusi title, description, uri, dataSource e updateTime.
    • id: l'identificatore del blocco all'interno del documento.
    • parent: il nome della risorsa del documento principale. Puoi passare questo valore al comando describe per recuperare il documento completo.
    • relevanceScore: il punteggio di pertinenza del segmento rispetto alla query di ricerca.

Recuperare un documento

Dopo aver trovato un blocco di documenti pertinente, utilizza il campo parent di questi risultati di ricerca per recuperare i contenuti Markdown completi del documento.

Esegui il comando gcloud developer-knowledge documents describe con il nome della risorsa del documento. Ad esempio, per recuperare il documento sulla creazione di bucket Cloud Storage, completa i seguenti passaggi:

  1. Esegui questo comando:

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

  2. Verifica che il comando restituisca i metadati e l'intero contenuto Markdown del documento:

    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

    L'output include i seguenti campi:

    • content: il testo Markdown completo del documento.
    • contentLengthBytes: la dimensione totale dei contenuti del documento in byte.
    • dataSource: il dominio della documentazione che ospita il documento.
    • description: un breve riepilogo del documento.
    • name: il nome univoco della risorsa del documento.
    • title: il titolo del documento.
    • updateTime: il timestamp dell'ultimo aggiornamento del documento.
    • uri: l'URL pubblico della pagina di documentazione.
    • view: la visualizzazione del documento restituita (DOCUMENT_VIEW_CONTENT, DOCUMENT_VIEW_BASIC o DOCUMENT_VIEW_FULL).

Passaggi successivi