Cercare e recuperare documenti

Questa guida fornisce esempi di come utilizzare le funzioni dell'API Developer Knowledge: ricerca di documenti, recupero di un singolo documento e recupero di più documenti in un batch.

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

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Cercare documenti con SearchDocumentChunks

Utilizza il metodo documents.searchDocumentChunks per trovare i blocchi di documenti che corrispondono a una stringa di query. I risultati includono blocchi di contenuti del documento e un riferimento parent che puoi utilizzare per recuperare i contenuti completi del documento.

L'esempio seguente cerca i documenti che corrispondono a "BigQuery":

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

Puoi perfezionare i risultati di ricerca utilizzando parametri come pageSize per limitare il numero di risultati per pagina e pageToken per recuperare le pagine successive.

Filtrare i risultati di ricerca

Utilizza il parametro filter per applicare un filtro rigoroso ai risultati di ricerca. Il filtro viene applicato ai metadati dei documenti associati ai blocchi di risultati di ricerca.

Campi supportati per il filtro:

  • data_source (STRING): l'origine del documento, ad esempio docs.cloud.google.com.
  • update_time (TIMESTAMP): il timestamp dell'ultimo aggiornamento del documento.
  • uri (STRING): l'URI del documento, ad esempio https://docs.cloud.google.com/bigquery/docs/tables.

Operatori supportati:

  • I campi STRING supportano = (uguale a) e != (diverso da) per le corrispondenze esatte dell'intera stringa.
  • I campi TIMESTAMP supportano =, <, <=, > e >=. I timestamp devono essere nel formato RFC-3339 (ad es. "2025-01-01T00:00:00Z").

Puoi combinare le espressioni utilizzando gli operatori logici AND, OR e NOT (o -). Tieni presente che OR ha la precedenza su AND.

L'esempio seguente cerca i documenti che corrispondono a "BigQuery" e limita i risultati a quelli provenienti da docs.cloud.google.com:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"

Recuperare un documento con GetDocument

Utilizza il metodo documents.get per recuperare l'intero contenuto di un singolo documento.

L'esempio seguente recupera un documento con il nome documents/DOCUMENT_ID:

curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"

La risposta è la risorsa Document completa, incluso il campo content.

Recuperare più documenti con BatchGetDocuments

Utilizza il metodo documents.batchGet per recuperare fino a 100 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/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"

La risposta contiene un elenco delle risorse Document richieste.