Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Cercare e recuperare documenti

Questo documento mostra come utilizzare l'API Developer Knowledge per cercare e recuperare in modo programmatico la documentazione per lo sviluppo pubblica di Google. Anziché eseguire lo scraping manuale delle pagine web, l'API aiuta le tue applicazioni a trovare snippet di testo pertinenti o a recuperare documenti Markdown completi.

In questo documento troverai esempi per le seguenti attività:

Ricerca nel corpus della documentazione.
Scorrere i risultati di ricerca.
Applicare filtri complessi alla ricerca.
Recupero dei contenuti completi del documento.
Ottimizzazione dei payload di risposta per ridurre la latenza.

Prima di iniziare, configura l'ambiente per lo strumento che preferisci:

gcloud

Installa e configura gcloud CLI e abilita l'API Developer Knowledge.

REST

Abilita l'API e genera una chiave API Developer Knowledge. Poi, salva la chiave in una variabile di ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Sostituisci YOUR_API_KEY con la chiave API Developer Knowledge.

Cercare documenti

Utilizza il comando gcloud developer-knowledge documents search-chunks o il metodo REST documents.searchDocumentChunks per trovare i blocchi di documenti che corrispondono a una stringa di query. I risultati includono blocchi di contenuti dei documenti corrispondenti, insieme a un riferimento parent che puoi utilizzare per recuperare i contenuti completi di questi documenti.

L'esempio seguente cerca i documenti corrispondenti a "BigQuery":

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

L'output è simile al seguente:

{
  "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
    }
  ]
}

Ogni risultato nell'elenco results include:

parent: il nome della risorsa documento (ad esempio, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: l'identificatore del blocco all'interno del documento (ad esempio, chunk_0).
content: lo snippet di testo corrispondente del documento.
document: metadati sul documento di origine, ad esempio title, uri, dataSource e updateTime.
relevanceScore: il punteggio di pertinenza del segmento rispetto alla query di ricerca, nell'intervallo [0.0, 1.0].

Per saperne di più sullo schema di risposta e su tutti i campi dei metadati disponibili, consulta il riferimento API documents.searchDocumentChunks.

Impagina i risultati di ricerca

Quando una query di ricerca restituisce più corrispondenze, puoi navigare nel set di risultati utilizzando i parametri di paginazione:

--page-size (gcloud CLI) o pageSize (numero intero): specifica il numero massimo di risultati da restituire per pagina. Se non specificato, l'API utilizza per impostazione predefinita cinque risultati. Il valore massimo consentito è 100; i valori superiori a 100 vengono forzati a 100.
--limit (gcloud CLI) o pageToken (stringa): in gcloud CLI, utilizza --limit per controllare il numero totale di risultati restituiti nelle pagine. Nelle richieste REST, passa il valore pageToken ricevuto in una risposta precedente per recuperare la pagina successiva dei risultati.

gcloud

Passa i flag --page-size e --limit per controllare il numero di risultati per pagina e il numero totale di risultati restituiti:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

Per richiedere la prima pagina, passa il parametro pageSize nella richiesta:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

Se sono disponibili risultati aggiuntivi, la risposta include un 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"
}

Per recuperare le pagine successive, trasmetti il valore di nextPageToken al parametro pageToken nella richiesta successiva:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Quando raggiungi l'ultima pagina dei risultati, nextPageToken viene omesso dalla risposta.

Filtrare i risultati di ricerca

Utilizza il flag --query-filter in gcloud CLI o il parametro filter nelle richieste REST per applicare un filtro rigoroso ai risultati di ricerca. L'espressione di filtro viene applicata ai metadati del documento principale per ogni chunk.

L'espressione di filtro ha un limite di caratteri di 500.

Campi supportati

Puoi filtrare i risultati di ricerca utilizzando i seguenti campi del documento principale:

content_length_bytes (integer): la lunghezza del campo content del documento in byte.
data_source (stringa): il dominio di origine del documento, ad esempio docs.cloud.google.com o firebase.google.com. Consulta il riferimento al corpus per tutte le origini dati supportate.
update_time (timestamp): il timestamp dell'ultimo aggiornamento del documento. I valori devono utilizzare il formato RFC 3339 (ad esempio, "2025-01-01T00:00:00Z").
uri (stringa): l'URI completo del documento (ad esempio, https://docs.cloud.google.com/bigquery/docs/tables).

Operatori supportati

L'analizzatore di espressioni di filtro supporta operatori diversi a seconda del tipo di dati del campo:

Campi stringa (data_source, uri): supportano = (uguale a) e != (diverso da) per la corrispondenza esatta delle stringhe. Le corrispondenze parziali, di prefisso e di espressioni regolari non sono supportate.
Campi timestamp (update_time): supportano =, <, <=, > e >=.
Campi interi (content_length_bytes): supportano =, !=, <, <=, > e >=.
Operatori logici: combina le condizioni utilizzando AND, OR e NOT (o -).

Esempi di filtro

Gli esempi riportati di seguito mostrano come creare espressioni di filtro. Quando utilizzi gcloud CLI, passa l'espressione al flag --query-filter. Quando chiami l'API REST con curl, assicurati di codificare l'URL del parametro filter o di utilizzare --data-urlencode.

Corrispondenza di una singola origine dati

Limita i risultati di ricerca a un singolo dominio di documentazione:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Corrispondenza di più origini dati

Utilizza OR per includere documenti provenienti da più fonti:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

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"

Filtra per timestamp

Utilizza gli operatori di confronto con i timestamp RFC 3339 per trovare i contenuti aggiornati dopo una data specifica:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

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"

Filtrare per durata dei contenuti

Utilizza gli operatori di confronto con content_length_bytes per trovare documenti in base alle dimensioni in byte:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

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"

Combinare origine dati, timestamp e raggruppamento

Combina AND, OR e le parentesi (...) per limitare i risultati a fonti specifiche aggiornate dopo una data specifica:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

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"

Escludere origini dati

Utilizza NOT o != per escludere i risultati da una fonte specifica:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

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"

Recuperare un documento

Utilizza il comando gcloud developer-knowledge documents describe o il metodo REST documents.get per recuperare l'intero contenuto di un singolo documento.

L'esempio seguente recupera un documento in base al nome della risorsa:

gcloud

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

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

La risposta è una risorsa Document contenente metadati e l'intero contenuto Markdown nel campo content.

Nomi delle risorse e URI

Quando fai riferimento ai documenti nell'API Developer Knowledge, tieni presente la differenza tra nomi delle risorse e URI web:

Nome risorsa (parent, name): formattato come documents/{uri_without_scheme} (ad esempio, documents/docs.cloud.google.com/storage/docs/creating-buckets). Trasferisci questo valore come argomento posizionale in gcloud developer-knowledge documents describe, come parametro di percorso in GetDocument o nel parametro names di BatchGetDocuments.
URI web (uri): URL web completo, incluso lo schema (ad esempio, https://docs.cloud.google.com/storage/docs/creating-buckets). Utilizza questo formato per il campo uri quando crei espressioni --query-filter o filter (ad esempio, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Recuperare più documenti con `BatchGetDocuments`

Utilizza il metodo documents.batchGet per recuperare fino a 20 documenti per nome in una singola chiamata API. Questo è più efficiente rispetto all'invio di più richieste GetDocument.

L'esempio seguente recupera due documenti per nome:

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"

La risposta contiene un elenco delle risorse Document richieste nell'ordine in cui le hai richieste.

Ottimizzare i payload di risposta

I contenuti del documento in formato Markdown possono essere di grandi dimensioni. Se la tua applicazione ha bisogno solo di metadati (come Titoli della pagina, URI o timestamp) o di campi specifici, puoi ottimizzare le dimensioni del payload per ridurre la larghezza di banda e la latenza.

Utilizzare le visualizzazioni dei documenti

Il flag --view in gcloud CLI o il parametro view nelle richieste REST controlla quali campi vengono compilati nei messaggi Document.

Il flag --view e l'enumerazione DocumentView supportano i seguenti valori:

--view=basic (gcloud CLI) o DOCUMENT_VIEW_BASIC: restituisce solo i campi dei metadati di base (name, uri, dataSource, title, description, updateTime e view). Il campo content viene omesso.
--view=content (gcloud CLI) o DOCUMENT_VIEW_CONTENT: restituisce i campi dei metadati insieme al campo Markdown content. Questo è il valore predefinito per gcloud developer-knowledge documents describe, GetDocument e BatchGetDocuments.
--view=full (gcloud CLI) o DOCUMENT_VIEW_FULL: restituisce tutti i campi del documento.

Per recuperare solo i metadati del documento senza scaricare contenuti Markdown di grandi dimensioni, specifica la visualizzazione di base del documento:

gcloud

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

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Puoi anche utilizzare view=DOCUMENT_VIEW_BASIC con 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"

Utilizzare le maschere di campo

Per limitare ulteriormente i payload di risposta a campi specifici, utilizza il parametro di query fields (maschera del campo) delle API Google standard.

Filtra campi in `GetDocument`

Per recuperare solo i campi title, uri e updateTime di un documento:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtra campi in `BatchGetDocuments`

Per recuperare solo campi specifici per ogni documento in un batch:

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"

Filtra campi in `SearchDocumentChunks`

Per restituire solo il blocco id e content, il documento principale title e uri e il nextPageToken da una ricerca:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

Gestisci gli errori

L'API Developer Knowledge restituisce codici di stato HTTP standard. I seguenti esempi funzionali mappano i codici di stato HTTP e le relative cause nell'API Developer Knowledge:

400 INVALID_ARGUMENT:
- La stringa dell'espressione filter supera i 500 caratteri.
- Il timestamp update_time non è valido (deve utilizzare il formato RFC 3339).
- In una BatchGetDocuments richiesta sono stati forniti più di 20 nomi di documenti.
401 UNAUTHENTICATED: la richiesta non include una chiave API o utilizza una chiave non valida. Consulta la sezione Autenticazione.
404 NOT_FOUND: il nome del documento richiesto non esiste o appartiene a un dominio non incluso nel corpus.
429 RESOURCE_EXHAUSTED: il progetto ha superato la quota. Consulta Quote e limiti.

Passaggi successivi

Consulta Generare risposte dalla documentazione.
Connettiti al server MCP Developer Knowledge e installa la skill dell'agente retrieving-developer-knowledge per aiutare l'assistenza al coding AI a cercare e leggere la documentazione ufficiale.
Scopri come utilizzare le librerie client in Python, Node.js, Go o Java.
Scopri come utilizzare gcloud CLI.
Sfoglia il riferimento del corpus per visualizzare tutte le origini della documentazione supportate.
Consulta il riferimento API REST per le specifiche complete dei metodi.
Controlla le quote e i limiti per i limiti di frequenza delle richieste API e le quote.

Cercare e recuperare documenti Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

gcloud

REST

Cercare documenti

gcloud

REST

Impagina i risultati di ricerca

gcloud

REST

Filtrare i risultati di ricerca

Campi supportati

Operatori supportati

Esempi di filtro

Corrispondenza di una singola origine dati

gcloud

REST

Corrispondenza di più origini dati

gcloud

REST

Filtra per timestamp

gcloud

REST

Filtrare per durata dei contenuti

gcloud

REST

Combinare origine dati, timestamp e raggruppamento

gcloud

REST

Escludere origini dati

gcloud

REST

Recuperare un documento

gcloud

REST

Nomi delle risorse e URI

Recuperare più documenti con BatchGetDocuments

Ottimizzare i payload di risposta

Utilizzare le visualizzazioni dei documenti

gcloud

REST

Utilizzare le maschere di campo

Filtra campi in GetDocument

Filtra campi in BatchGetDocuments

Filtra campi in SearchDocumentChunks

Gestisci gli errori

Passaggi successivi

Cercare e recuperare documenti

Recuperare più documenti con `BatchGetDocuments`

Filtra campi in `GetDocument`

Filtra campi in `BatchGetDocuments`

Filtra campi in `SearchDocumentChunks`