Commencer à utiliser l'API Data Portability

Dans ce guide de démarrage rapide, vous obtenez un jeton OAuth pour votre compte et envoyez des requêtes ponctuelles aux points de terminaison de l'API Data Portability.

Ce guide de démarrage rapide explique comment utiliser l'API Data Portability pour accéder une seule fois aux données utilisateur. Pour accéder de manière continue aux données utilisateur, consultez Utiliser l'accès basé sur le temps. Pour savoir comment appliquer des filtres temporels à votre requête, consultez Appliquer des filtres temporels.

Objectifs

Dans ce guide de démarrage rapide, vous allez apprendre à:

  • Envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive en fournissant un jeton OAuth valide. La réponse doit contenir un job_id valide.
  • Envoyez une requête authentifiée au point de terminaison GetPortabilityArchiveState. La réponse doit contenir un état de tâche valide et, une fois la tâche terminée, une URL signée.
  • (Facultatif) Envoyez une requête authentifiée avec un jeton OAuth valide au point de terminaison InitiatePortabilityArchive une deuxième fois à l'aide des mêmes identifiants. Cela renvoie une erreur RESOURCE_EXHAUSTED et vise à souligner l'importance du point de terminaison ResetAuthorization.
  • Envoyez une requête authentifiée au point de terminaison ResetAuthorization. Cette requête révoque toutes les habilitations OAuth accordées par l'utilisateur.
  • (Facultatif) Envoyez une requête au point de terminaison InitiatePortabilityArchive à l'aide du même jeton OAuth que celui que vous avez utilisé précédemment. La requête doit échouer après la réinitialisation de l'autorisation.

Prérequis

Pour exécuter ce guide de démarrage rapide, vous devez:

  • Vérifiez que l'API Data Portability est disponible pour les utilisateurs de votre région. Pour obtenir la liste des pays et régions compatibles, consultez les questions fréquentes sur la page "Partager une copie de vos données avec un tiers".
  • Suivez les étapes de configuration de l'API Data Portability.
  • Suivez la procédure pour configurer OAuth pour les applications Web JavaScript. En production, vous utilisez normalement un flux différent, comme le flux OAuth pour les applications de serveur Web. Pour des raisons de simplicité, ce guide de démarrage rapide utilise le flux d'application Web JavaScript.
    • Lorsque vous créez vos identifiants d'autorisation, notez votre ID client OAuth 2.0 et votre URI de redirection autorisé (par exemple, https://google.com). Vous en aurez besoin plus loin dans le guide de démarrage rapide.
    • Lorsque vous configurez des champs d'application pour l'API Data Portability, notez que ce guide de démarrage rapide utilise le groupe de ressources myactivity.search : https://www.googleapis.com/auth/dataportability.myactivity.search.
    • Lorsque vous choisissez la durée pendant laquelle vous souhaitez autoriser l'accès, ce tutoriel de démarrage utilise un accès ponctuel.
  • Obtenez un jeton OAuth.
  • Obtenir l'accès à un compte appartenant ou contrôlé par votre organisation Les données d'activité de recherche de ce compte sont exportées dans ce guide de démarrage rapide.

Obtenir un jeton OAuth

Pour ce guide de démarrage rapide, vous envoyez une requête d'autorisation pour obtenir un jeton OAuth à l'aide d'une URL. Ce processus utilise le flux pour les applications Web JavaScript. Ce flux ne renvoie pas de jeton de rafraîchissement.

Pour une application de production, vous utilisez généralement un flux OAuth pour obtenir un jeton d'actualisation qui peut être utilisé pour générer des jetons d'accès à la demande. C'est le cas, par exemple, du flux des applications Web côté serveur.

Pour obtenir un jeton OAuth:

  1. Composez une URL semblable à celle-ci.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value

    Dans l'URL:

    • client_id correspond à votre ID client OAuth.
    • redirect_uri est votre URI de redirection autorisé (par exemple, https://google.com).

    Notez que le champ d'application utilisé dans l'URL de ce guide de démarrage rapide est le champ d'application de l'activité de recherche. Vous pouvez également utiliser le champ d'application "Activité YouTube" ou les deux champs d'application.

  2. Collez l'URL dans la barre d'adresse de votre navigateur, puis suivez la procédure du flux OAuth. Ce flux vous oblige à vous connecter au compte appartenant ou contrôlé par votre organisation que vous utilisez pour ce guide de démarrage rapide.

    Il s'agit du compte qui accepte les champs d'application OAuth. L'écran de consentement doit se présenter comme suit (le texte affiché sur votre écran peut différer de celui de cette image):

    Écran de consentement sur lequel l'utilisateur autorise l'accès aux données de son activité de recherche

  3. Choisissez les champs d'application auxquels accorder l'accès et la durée de partage de l'accès aux données du compte (une fois, 30 jours ou 180 jours). Pour ce guide de démarrage rapide, choisissez Une seule fois.

  4. Après avoir donné votre consentement et choisi la durée d'accès, vous devriez être redirigé vers l'URI de redirection : https://google.com. L'URL générée dans la barre d'adresse inclut le jeton d'accès OAuth.

    Par exemple, si le compte utilisateur accorde un accès OAuth au champ d'application dataportability.myactivity.search, l'URL générée se présente comme suit:

    https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

    Dans l'URL, your_OAuth_token est une chaîne qui représente le jeton.

  5. Pour valider le jeton OAuth, collez cette URL dans votre navigateur:

    https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

    La réponse doit se présenter comme suit:

    {
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}

    Vous n'avez pas besoin des champs azp ou aud pour effectuer des requêtes. Le champ azp représente le client_id du présentateur autorisé, et le champ aud identifie l'audience à laquelle ce jeton est destiné, qui sera égale à l'un des ID client de votre application.

  6. Rassemblez votre jeton OAuth et votre clé API. Vous en avez besoin pour effectuer des appels à l'API Data Portability.

Envoyer des requêtes aux points de terminaison

Dans ce guide de démarrage rapide, vous allez utiliser des commandes curl pour appeler les points de terminaison de l'API Data Portability. Ces commandes nécessitent le jeton OAuth et la clé API que vous avez collectés précédemment.

Pour appeler l'API Data Portability:

  1. Tout d'abord, vous envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive. Cette requête lance une tâche d'archivage.

    Exécutez la commande curl suivante:

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Dans la commande :

    • your_OAuth_token est votre jeton OAuth.

    La requête InitiatePortabilityArchive renvoie un job_id et un accessType. L'ID de tâche permet de récupérer l'état de l'archive de données, et le type d'accès détermine si vous avez été autorisé à accéder aux données de manière ponctuelle ou temporelle. Pour les besoins de ce guide de démarrage rapide, vous devez disposer d'un accès unique.

    {
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}

    Si vous ne fournissez pas de jeton OAuth valide, le message d'erreur suivant s'affiche: 

    Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.

  2. Vous envoyez ensuite une requête authentifiée au point de terminaison GetPortabilityArchiveState pour récupérer l'état de la tâche d'archivage.

    Exécutez la commande curl suivante:

    curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

    Dans la commande :

    • your_OAuth_token est votre jeton OAuth.
    • your_job_id est l'ID de la tâche renvoyé par la requête InitiatePortabilityArchive.

    La réponse est basée sur l'état de la tâche. Si la tâche n'est pas terminée, la réponse indique l'état actuel. Vous devez envoyer des requêtes à ce point de terminaison régulièrement jusqu'à ce que la tâche soit terminée.

    {
  "state": "IN_PROGRESS"
}

    Si la tâche est terminée, la réponse contient l'état et une ou plusieurs URL signées utilisées pour télécharger l'archive de données.

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    Collez l'URL signée dans votre navigateur pour télécharger l'archive de données. Vous devez examiner le contenu de l'archive pour vous assurer qu'il contient les données d'activité de recherche attendues.

  3. (Facultatif) Répétez la commande précédente pour envoyer une requête authentifiée au point de terminaison InitiatePortabilityArchive.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Dans la commande :

    • your_OAuth_token est votre jeton OAuth.

    La réponse doit indiquer que le consentement unique pour la ressource myactivity.search est épuisé pour cet utilisateur.

    ...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

  4. Envoyez une requête authentifiée au point de terminaison ResetAuthorization. Cette requête révoque toutes les habilitations OAuth accordées par l'utilisateur et vous permet d'appeler InitiatePortabilityArchive pour un groupe de ressources que vous avez déjà utilisé.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    Dans la commande :

    • your_OAuth_token est votre jeton OAuth.

    Cette commande renvoie une réponse vide.

  5. (Facultatif) Après avoir réinitialisé l'autorisation, envoyez une autre requête au point de terminaison InitiatePortabilityArchive. Utilisez la même commande curl que précédemment.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Dans la commande :

    • your_OAuth_token est votre jeton OAuth.

    La réponse doit renvoyer une erreur, car le jeton OAuth que vous avez fourni a été révoqué.

    ...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }