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 a livello di programmazione la documentazione per lo sviluppo pubblica di Google. Anziché eseguire manualmente lo scraping delle pagine web, l'API aiuta le 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.
Scorrimento dei risultati di ricerca tramite impaginazione.
Applicazione di filtri complessi alla ricerca.
Recupero dei contenuti completi dei documenti.
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 attiva l'API Developer Knowledge.

REST

Attiva 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 tua chiave API Developer Knowledge.

Cercare documenti

Utilizza il gcloud developer-knowledge documents search-chunks comando o il documents.searchDocumentChunks metodo REST per trovare 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 che corrispondono 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 del 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, come title, uri, dataSource e updateTime.
relevanceScore: il punteggio di pertinenza del blocco rispetto alla query di ricerca, nell'intervallo [0.0, 1.0].

Per ulteriori informazioni sullo schema di risposta e su tutti i campi di metadati disponibili, consulta il riferimento API documents.searchDocumentChunks.

Scorrere i risultati di ricerca tramite impaginazione

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

--page-size (gcloud CLI) o pageSize (integer): 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 (string): in gcloud CLI, utilizza --limit per controllare il numero totale di risultati restituiti tra le 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 altri risultati, 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, passa 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 filter parametro 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 blocco.

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 (string): il dominio di origine del documento, ad esempio docs.cloud.google.com o firebase.google.com. Consulta il riferimento del 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 (string): l'URI completo del documento (ad esempio, https://docs.cloud.google.com/bigquery/docs/tables).

Operatori supportati

Il parser delle 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 seguenti 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 con 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 con più origini dati

Utilizza OR per includere documenti di più origini:

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"

Filtrare 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 lunghezza dei contenuti

Utilizza gli operatori di confronto con content_length_bytes per trovare i documenti in base alle loro 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 origini specifiche aggiornate dopo una determinata data:

(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 le origini dati

Utilizza NOT o != per escludere i risultati da un'origine 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 gcloud developer-knowledge documents describe comando o il documents.get metodo REST per recuperare i contenuti completi 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 Document risorsa contenente i metadati e i contenuti Markdown completi nel campo content.

Nomi delle risorse e URI

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

Nome della risorsa (parent, name): formattato come documents/{uri_without_scheme} (ad esempio, documents/docs.cloud.google.com/storage/docs/creating-buckets). Passa 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 documents.batchGet metodo 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 richieste Document nell'ordine in cui le hai richieste.

Ottimizzare i payload di risposta

I contenuti dei documenti 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 dei 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 Document messaggi.

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

--view=basic (gcloud CLI) o DOCUMENT_VIEW_BASIC: restituisce solo i campi di 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 di metadati insieme al campo content Markdown. 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 dei documenti senza scaricare contenuti Markdown di grandi dimensioni, specifica la visualizzazione di base dei documenti:

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 delle API Google standard (maschera di campo).

Filtrare i 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"

Filtrare i 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"

Filtrare i campi in `SearchDocumentChunks`

Per restituire solo id e content del blocco, title e uri del documento principale e 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"

Gestire gli errori

L'API Developer Knowledge restituisce codici di stato HTTP standard. Gli esempi funzionali seguenti 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 richiesta BatchGetDocuments sono stati forniti più di 20 nomi di documenti.
401 UNAUTHENTICATED: la richiesta non include una chiave API o un token di autenticazione o utilizza credenziali non valide. 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 sua quota. Consulta la sezione Quote e limiti.

Passaggi successivi

Consulta Generare risposte dalla documentazione.
Connettiti al server MCP di Developer Knowledge e installa la retrieving-developer-knowledge skill dell'agente 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 di documentazione supportate.
Consulta il riferimento API REST per le specifiche complete dei metodi.
Controlla le quote e i limiti per le quote e i limiti di frequenza delle richieste API.

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

Scorrere i risultati di ricerca tramite impaginazione

gcloud

REST

Filtrare i risultati di ricerca

Campi supportati

Operatori supportati

Esempi di filtro

Corrispondenza con una singola origine dati

gcloud

REST

Corrispondenza con più origini dati

gcloud

REST

Filtrare per timestamp

gcloud

REST

Filtrare per lunghezza dei contenuti

gcloud

REST

Combinare origine dati, timestamp e raggruppamento

gcloud

REST

Escludere le 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

Filtrare i campi in GetDocument

Filtrare i campi in BatchGetDocuments

Filtrare i campi in SearchDocumentChunks

Gestire gli errori

Passaggi successivi

Cercare e recuperare documenti

Recuperare più documenti con `BatchGetDocuments`

Filtrare i campi in `GetDocument`

Filtrare i campi in `BatchGetDocuments`

Filtrare i campi in `SearchDocumentChunks`