Rechercher et récupérer des documents

Ce document explique comment utiliser l'API Developer Knowledge pour rechercher et récupérer par programmation la documentation pour les développeurs publique 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 :

  • Rechercher dans le corpus de documentation
  • Parcourir les résultats de recherche
  • Appliquer des filtres complexes à votre recherche
  • Récupérer le contenu complet d'un document
  • Optimiser les 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 la 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 gcloud developer-knowledge documents search-chunks commande ou la documents.searchDocumentChunks méthode REST pour trouver des fragments de document qui correspondent à une chaîne de requête. Les résultats incluent des fragments 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 des 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 la ressource du document (par exemple, documents/docs.cloud.google.com/bigquery/docs/introduction).
  • id : identifiant du fragment 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 fragment 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 de paramètres de pagination :

  • --page-size (gcloud CLI) ou 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.

  • --limit (gcloud CLI) ou pageToken (chaîne) : dans la gcloud CLI, utilisez --limit pour contrôler le nombre total de résultats renvoyés sur toutes 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 options --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 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 l'option --query-filter dans la gcloud CLI ou le filter paramètre 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 fragment.

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. 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 utiliser le 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 accepte différents opérateurs en fonction du type de données du champ :

  • Champs de 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 code temporel (update_time) : acceptent =, <, <=, >, et >=.
  • Champs d'entiers (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 utilisez la gcloud CLI, transmettez l'expression à l'option --query-filter. Lorsque vous appelez l'API REST avec curl, veillez à encoder l'URL du paramètre filter ou à utiliser --data-urlencode.

Faire correspondre une seule source de données

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

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"

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

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 gcloud developer-knowledge documents describe commande ou la documents.get méthode REST pour récupérer le contenu complet d'un seul 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 Document ressource contenant des métadonnées et le contenu Markdown complet 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 la ressource (parent, name) : formaté comme documents/{uri_without_scheme} (par exemple, documents/docs.cloud.google.com/storage/docs/creating-buckets). Transmettez cette valeur comme argument positionnel dans gcloud developer-knowledge documents describe, comme 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 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 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 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 des vues de document

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

L'option --view et l'DocumentView enum 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 content Markdown. 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 document de base :

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

Filtrer les champs 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"

Filtrer les champs 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 le id et le content du fragment, 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 utiliser le 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 ni de jeton porteur, ou utilise des identifiants non valides. 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