Cercare e recuperare documenti

Questa guida mostra come utilizzare l'API Developer Knowledge per cercare e recuperare in modo programmatico la documentazione per sviluppatori 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 delle pagine dei risultati di ricerca.
  • Applicazione di filtri complessi alla ricerca.
  • Recupero dei contenuti completi dei documenti.
  • Ottimizzazione dei payload di risposta per ridurre la latenza.

Prima di iniziare, assicurati di aver abilitato l'API e generato una chiave API Developer Knowledge. Poi, salva la chiave in una variabile di ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Cercare documenti con SearchDocumentChunks

Utilizza il documents.searchDocumentChunks metodo 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":

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 dei metadati disponibili, consulta il riferimento API documents.searchDocumentChunks.

Scorrere le pagine dei risultati di ricerca

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

  • pageSize (integer): specifica il numero massimo di risultati da restituire per pagina. Se non viene specificato, l'API utilizza per impostazione predefinita cinque risultati. Il valore massimo consentito è 100; i valori superiori a 100 vengono forzati a 100.
  • pageToken (string): specifica il token ricevuto in una risposta precedente per recuperare la pagina successiva dei risultati.

Richiedere la prima pagina

Per impostare le dimensioni della 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"
}

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 parametro filter 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 filter ha un limite di 500 caratteri.

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 chiami l'API REST con curl, assicurati di codificare l'URL del parametro di filtro o di utilizzare --data-urlencode.

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"

Richiesta curl:

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"

Richiesta curl:

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 dimensioni in byte:

content_length_bytes < 5000

Richiesta curl:

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

Richiesta curl:

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"

Richiesta curl:

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 con GetDocument

Utilizza il documents.get metodo per recuperare i contenuti completi di un singolo documento.

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 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 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 filter (ad esempio, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

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

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.

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'esecuzione 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 di pagine, 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 parametro view controlla quali campi vengono compilati nei Document messaggi.

L'DocumentView enumerazione supporta i seguenti valori:

  • DOCUMENT_VIEW_BASIC: restituisce solo i campi dei metadati di base (name, uri, data_source, title, description, update_time e view). Il campo content viene omesso.
  • DOCUMENT_VIEW_CONTENT: restituisce i campi dei metadati insieme al campo content Markdown. Questo è il valore predefinito per GetDocument e BatchGetDocuments.
  • DOCUMENT_VIEW_FULL: restituisce tutti i campi del documento.

Per recuperare solo i metadati dei documenti senza scaricare contenuti Markdown di grandi dimensioni, imposta view=DOCUMENT_VIEW_BASIC:

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"

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 utilizza una chiave non valida. Consulta 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 Quota e limiti.

Passaggi successivi