Rechercher et récupérer des documents

Ce guide explique comment utiliser l'API Developer Knowledge pour rechercher et récupérer par programmation la documentation publique pour les développeurs de Google. Au lieu d'extraire manuellement des pages Web, l'API aide vos applications à trouver des extraits de texte pertinents ou à récupérer des documents Markdown complets.

Ce document contient des exemples pour les tâches suivantes :

  • Recherche dans le corpus de documentation.
  • Pagination des résultats de recherche.
  • Application de filtres complexes à votre recherche.
  • Récupération du contenu complet d'un document.
  • Optimisation des charges utiles de réponse pour réduire la latence.

Avant de commencer, assurez-vous d'avoir activé l'API et généré une clé API Developer Knowledge. Ensuite, enregistrez votre clé dans une variable d'environnement :

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Rechercher des documents avec SearchDocumentChunks

Utilisez la documents.searchDocumentChunks méthode pour trouver des blocs de documents correspondant à une chaîne de requête. Les résultats incluent des blocs de contenu provenant de documents correspondants, ainsi qu'une référence parent que vous pouvez utiliser pour récupérer le contenu complet de ces documents.

L'exemple suivant recherche les documents correspondant à "BigQuery" :

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

Le résultat ressemble à ce qui suit :

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

Chaque résultat de la liste results inclut les éléments suivants :

  • parent: nom de la ressource du document (par exemple, documents/docs.cloud.google.com/bigquery/docs/introduction).
  • id : identifiant du bloc dans le document (par exemple, chunk_0).
  • content : extrait de texte correspondant du document.
  • document: métadonnées sur le document source, telles que title, uri, dataSource et updateTime.
  • relevanceScore: score de pertinence du bloc par rapport à la requête de recherche, dans la plage [0.0, 1.0].

Pour en savoir plus sur le schéma de réponse et tous les champs de métadonnées disponibles, consultez la documentation de référence de l'API documents.searchDocumentChunks.

Pagination des résultats de recherche

Lorsqu'une requête de recherche renvoie plusieurs correspondances, vous pouvez parcourir l'ensemble de résultats à l'aide des paramètres de pagination suivants :

  • pageSize (entier) : spécifie le nombre maximal de résultats à renvoyer par page. Si ce paramètre n'est pas spécifié, l'API renvoie cinq résultats par défaut. La valeur maximale autorisée est 100. Les valeurs supérieures à 100 sont forcées à 100.
  • pageToken (chaîne) : spécifie le jeton reçu dans une réponse précédente pour récupérer la page de résultats suivante.

Demander la première page

Pour définir la taille de la page, transmettez le paramètre pageSize dans votre requête :

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

Si des résultats supplémentaires sont disponibles, la réponse inclut 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"
}

Récupérer les pages suivantes

Transmettez la valeur de nextPageToken au paramètre pageToken dans votre requête suivante :

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

Lorsque vous atteignez la dernière page de résultats, nextPageToken est omis de la réponse.

Filtrer les résultats de recherche

Utilisez le paramètre filter pour appliquer un filtre strict aux résultats de recherche. L'expression de filtre est appliquée aux métadonnées du document parent pour chaque bloc.

L'expression filter est limitée à 500 caractères.

Champs pris en charge

Vous pouvez filtrer vos résultats de recherche à l'aide des champs de document parent suivants :

  • content_length_bytes (entier) : longueur du champ content du document en octets.
  • data_source (chaîne) : domaine source du document, tel que docs.cloud.google.com ou firebase.google.com. Consultez la documentation de référence du corpus pour connaître toutes les sources de données compatibles.
  • update_time (code temporel) : code temporel de la dernière mise à jour du document. Les valeurs doivent être au format RFC 3339 (par exemple, "2025-01-01T00:00:00Z").
  • uri (chaîne) : URI complet du document (par exemple, https://docs.cloud.google.com/bigquery/docs/tables).

Opérateurs compatibles

L'analyseur d'expressions de filtre est compatible avec différents opérateurs en fonction du type de données du champ :

  • Champs de type chaîne (data_source, uri) : acceptent = (égal à) et != (différent de) pour une correspondance exacte des chaînes. Les correspondances partielles, de préfixe et d'expression régulière ne sont pas acceptées.
  • Champs de type code temporel (update_time) : acceptent =, <, <=, >, et >=.
  • Champs de type entier (content_length_bytes) : acceptent =, !=, <, <=, > et >=.
  • Opérateurs logiques : combinent des conditions à l'aide de AND, OR et NOT (ou -).

Exemples de filtres

Les exemples suivants montrent comment créer des expressions de filtre. Lorsque vous appelez l'API REST avec curl, veillez à encoder au format URL le paramètre de filtre ou à utiliser --data-urlencode.

Faire correspondre plusieurs sources de données

Utilisez OR pour inclure des documents provenant de plusieurs sources :

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

Requête 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"

Filtrer par code temporel

Utilisez des opérateurs de comparaison avec des codes temporels RFC 3339 pour trouver le contenu mis à jour après une date spécifique :

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

Requête 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"

Filtrer par longueur de contenu

Utilisez des opérateurs de comparaison avec content_length_bytes pour trouver des documents en fonction de leur taille en octets :

content_length_bytes < 5000

Requête 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"

Combiner la source de données, le code temporel et le regroupement

Combinez AND, OR et des parenthèses (...) pour limiter les résultats à des sources spécifiques mises à jour après une date donnée :

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

Requête 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"

Exclure des sources de données

Utilisez NOT ou != pour exclure les résultats d'une source spécifique :

data_source != "firebase.google.com"

Requête 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"

Récupérer un document avec GetDocument

Utilisez la documents.get méthode pour récupérer le contenu complet d'un seul document.

Noms de ressources et URI

Lorsque vous référencez des documents dans l'API Developer Knowledge, notez la différence entre les noms de ressources et les URI Web :

  • Nom de la ressource (parent, name) : formaté comme documents/{uri_without_scheme} (par exemple, documents/docs.cloud.google.com/storage/docs/creating-buckets). Transmettez cette valeur en tant que paramètre de chemin dans GetDocument ou dans le paramètre names de BatchGetDocuments.
  • URI Web (uri) : URL Web complète, y compris le schéma (par exemple, https://docs.cloud.google.com/storage/docs/creating-buckets). Utilisez ce format pour le champ uri lorsque vous créez des expressions filter (par exemple, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

L'exemple suivant récupère un document par son nom de ressource :

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

La réponse est une Document ressource contenant des métadonnées et le contenu Markdown complet dans le champ content.

Récupérer plusieurs documents avec BatchGetDocuments

Utilisez la documents.batchGet méthode pour récupérer jusqu'à 20 documents par nom en un seul appel d'API. Cette méthode est plus efficace que d'effectuer plusieurs requêtes GetDocument.

L'exemple suivant récupère deux documents par leur nom :

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 réponse contient une liste des ressources demandées Document dans l'ordre de votre requête.

Optimiser les charges utiles de réponse

Le contenu des documents au format Markdown peut être volumineux. Si votre application n'a besoin que de métadonnées (telles que les titres de page, les URI ou les codes temporels) ou de champs spécifiques, vous pouvez optimiser la taille des charges utiles pour réduire la bande passante et la latence.

Utiliser des vues de document

Le paramètre view contrôle les champs renseignés dans les messages Document.

L'énumération DocumentView accepte les valeurs suivantes :

  • DOCUMENT_VIEW_BASIC: ne renvoie que les champs de métadonnées de base (name, uri, data_source, title, description, update_time et view). Le champ content est omis.
  • DOCUMENT_VIEW_CONTENT: renvoie les champs de métadonnées ainsi que le champ content Markdown. Il s'agit de la valeur par défaut pour GetDocument et BatchGetDocuments.
  • DOCUMENT_VIEW_FULL : renvoie tous les champs du document.

Pour ne récupérer que les métadonnées du document sans télécharger de contenu Markdown volumineux, définissez 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"

Vous pouvez également utiliser view=DOCUMENT_VIEW_BASIC avec 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"

Utiliser des masques de champ

Pour limiter davantage les charges utiles de réponse à des champs spécifiques, utilisez le paramètre de requête standard des API Google fields (masque de champ).

Filtrer les champs dans GetDocument

Pour ne récupérer que les champs title, uri et updateTime d'un document :

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

Filtrer les champs dans BatchGetDocuments

Pour ne récupérer que des champs spécifiques pour chaque document d'un lot :

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"

Pour ne renvoyer que l'id et le content du bloc, le title et l'uri du document parent, ainsi que le nextPageToken d'une recherche :

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

Gérer les erreurs

L'API Developer Knowledge renvoie des codes d'état HTTP standards. Les exemples fonctionnels suivants mettent en correspondance les codes d'état HTTP et leurs causes dans l'API Developer Knowledge :

  • 400 INVALID_ARGUMENT:
    • La chaîne d'expression filter dépasse 500 caractères.
    • Le code temporel update_time n'est pas valide (doit être au format RFC 3339).
    • Plus de 20 noms de documents ont été fournis dans une requête BatchGetDocuments.
  • 401 UNAUTHENTICATED: la requête ne contient pas de clé API ou utilise une clé non valide. Consultez la section Authentification.
  • 404 NOT_FOUND: le nom de document demandé n'existe pas ou appartient à un domaine qui n'est pas inclus dans le corpus.
  • 429 RESOURCE_EXHAUSTED: le projet a dépassé son quota. Consultez la section Quotas et limites.

Étape suivante