Rechercher et récupérer des documents

Ce document explique comment utiliser l'API Developer Knowledge pour rechercher et récupérer de manière programmatique 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.

Dans ce document, vous trouverez des exemples pour les tâches suivantes :

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

Avant de commencer, configurez votre environnement pour l'outil de votre choix :

gcloud

Installez et configurez gcloud CLI, puis activez l'API Developer Knowledge.

REST

Activez l'API et générez une clé API Developer Knowledge. Ensuite, enregistrez votre clé dans une variable d'environnement :

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Remplacez YOUR_API_KEY par votre clé API Developer Knowledge.

Rechercher des documents

Utilisez la commande gcloud developer-knowledge documents search-chunks ou la méthode REST documents.searchDocumentChunks pour trouver les blocs de documents qui correspondent à une chaîne de requête. Les résultats incluent des blocs de contenu provenant des documents correspondants, ainsi qu'une référence parent que vous pouvez utiliser pour récupérer l'intégralité du contenu de ces documents.

L'exemple suivant recherche les documents correspondant à "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"

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 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 dans le 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.

Paginer les 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 :

  • --page-size (gcloud CLI) ou pageSize (entier) : spécifie le nombre maximal de résultats à renvoyer par page. Si aucune valeur n'est spécifiée, l'API renvoie cinq résultats par défaut. La valeur maximale autorisée est de 100. Les valeurs supérieures sont réduites à 100.

  • --limit (gcloud CLI) ou pageToken (chaîne) : dans gcloud CLI, utilisez --limit pour contrôler le nombre total de résultats renvoyés sur les pages. Dans les requêtes REST, transmettez la valeur pageToken reçue dans une réponse précédente pour extraire la page de résultats suivante.

gcloud

Transmettez les indicateurs --page-size et --limit pour contrôler le nombre de résultats par page et le nombre total de résultats renvoyés :

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

REST

  1. Pour demander la première 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"
}

  2. Pour récupérer les pages suivantes, transmettez la valeur de nextPageToken au paramètre pageToken de votre prochaine requête :

    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 l'option --query-filter dans la gcloud CLI ou le paramètre filter dans les requêtes REST 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 de filtre 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. Pour connaître toutes les sources de données compatibles, consultez la documentation de référence sur le corpus.
  • 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 :

  • Les champs de chaîne (data_source, uri) sont compatibles avec = (égal à) et != (différent de) pour la mise en correspondance exacte des chaînes. Les correspondances partielles, de préfixe et d'expression régulière ne sont pas acceptées.
  • Champs d'horodatage (update_time) : compatibles avec =, <, <=, > et >=.
  • Les champs entiers (content_length_bytes) acceptent =, !=, <, <=, > et >=.
  • Opérateurs logiques : combinez 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 utilisez la CLI gcloud, transmettez l'expression à l'option --query-filter. Lorsque vous appelez l'API REST avec curl, veillez à encoder au format URL le paramètre filter ou à utiliser --data-urlencode.

Faire correspondre une seule source de données

Limiter les résultats de recherche à un seul domaine de documentation :

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"

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

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"

Filtrer par code temporel

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

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"

Filtrer par durée du 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

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"

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"

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"

Exclure des sources de données

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

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"

Récupérer un document

Utilisez la commande gcloud developer-knowledge documents describe ou la méthode REST documents.get pour récupérer l'intégralité du contenu d'un document.

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

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 réponse est une ressource Document contenant des métadonnées et l'intégralité du contenu Markdown dans le champ content.

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 ressource (parent, name) : au format documents/{uri_without_scheme} (par exemple, documents/docs.cloud.google.com/storage/docs/creating-buckets). Transmettez cette valeur en tant qu'argument positionnel dans gcloud developer-knowledge documents describe, paramètre de chemin d'accès 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 --query-filter ou filter (par exemple, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Récupérer plusieurs documents avec BatchGetDocuments

Utilisez la méthode documents.batchGet pour récupérer jusqu'à 20 documents par nom dans 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 Document demandées, dans l'ordre dans lequel vous les avez demandées.

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 la 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 les vues de document

L'option --view dans la CLI gcloud ou le paramètre view dans les requêtes REST contrôlent les champs renseignés dans les messages Document.

L'option --view et l'enum DocumentView acceptent les valeurs suivantes :

  • --view=basic (gcloud CLI) ou DOCUMENT_VIEW_BASIC : ne renvoie que les champs de métadonnées de base (name, uri, dataSource, title, description, updateTime et view). Le champ content est omis.
  • --view=content (gcloud CLI) ou DOCUMENT_VIEW_CONTENT : renvoie les champs de métadonnées ainsi que le champ Markdown content. Il s'agit de la valeur par défaut pour gcloud developer-knowledge documents describe, GetDocument et BatchGetDocuments.
  • --view=full (gcloud CLI) ou DOCUMENT_VIEW_FULL : renvoie tous les champs du document.

Pour récupérer uniquement les métadonnées du document sans télécharger de contenu Markdown volumineux, spécifiez la vue de base du document :

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"

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 fields (masque de champ) des API Google standards.

Champs de filtre dans GetDocument

Pour récupérer uniquement 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"

Champs de filtre dans BatchGetDocuments

Pour récupérer uniquement 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 les blocs id et content, les documents parents title et uri, et 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 mappent 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 (il doit être au format RFC 3339).
    • Plus de 20 noms de documents ont été fournis dans une demande BatchGetDocuments.
  • 401 UNAUTHENTICATED : la requête ne contient pas de clé API ou utilise une clé non valide. Consultez Authentification.
  • 404 NOT_FOUND : le nom du 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 Quotas et limites.

Étape suivante