Les nouvelles fonctionnalités de l'API Data Portability sont en cours de déploiement et seront disponibles pour tous d'ici le 20 février 2025.

Cette page a été traduite par l'API Cloud Translation.

Utiliser l'accès basé sur l'heure

Dans ce guide de démarrage rapide, vous obtenez un jeton OAuth pour votre compte et vous envoyez des requêtes récurrentes 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 aux données utilisateur de manière temporelle. Pour accéder une seule fois aux données utilisateur, consultez la section Commencer à utiliser l'API Data Portability. 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.
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. Une erreur FAILED_PRECONDITION est renvoyée lorsque la requête est effectuée dans les 24 heures suivant la requête initiale.

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 de configuration d'OAuth pour les applications Web côté serveur.
- Lorsque vous créez vos identifiants d'autorisation, notez votre ID client OAuth 2.0, votre secret client et votre URI de redirection autorisé (par exemple, https://google.com). Vous en aurez besoin plus loin dans ce 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, sélectionnez 30 jours pour tester l'accès basé sur le temps.
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 côté serveur. Ce flux génère un jeton d'actualisation que vous pouvez utiliser pour les exportations ultérieures.

Pour obtenir un jeton OAuth:

Complétez une URL comme suit.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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.

Avertissement :Ne mélangez pas les champs d'application de l'API Portabilité des données avec d'autres types de champs d'application, n'utilisez pas trop de champs d'application à la fois et n'incluez pas de champs d'application précédemment accordés, car cela entraînerait des erreurs. Pour en savoir plus, consultez Restrictions de champ d'application.
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 de votre écran peut différer de celui de cette image):
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 30 jours.
Une fois que vous avez donné votre autorisation et défini 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 un code d'autorisation que vous échangerez contre un jeton OAuth à l'étape suivante.

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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
Pour échanger un code d'autorisation contre un jeton d'accès, appelez le point de terminaison du jeton OAuth avec:
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'
```
La réponse doit se présenter comme suit:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}
```
Dans l'URL, your_OAuth_token est une chaîne qui représente le jeton.

Le champ refresh_token_expires_in est exprimé en secondes et indique si l'utilisateur a choisi un accès de 30 jours (2 592 000 secondes) ou de 180 jours (1 555 2000 secondes). Si l'état de publication de votre application est Tests, vous disposez de sept jours (604 800 secondes) d'accès, quelle que soit la sélection de l'utilisateur.

Important :Votre jeton d'accès OAuth expire dans une heure. Stockez votre jeton d'actualisation afin qu'il puisse être échangé contre de nouveaux jetons d'accès plus tard.
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.

Remarque :Vous pouvez également vérifier le jeton en envoyant une requête HTTP GET.
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:

Tout d'abord, vous envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive. Cette requête lance un job 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.
Avertissement :Le paramètre resources ne doit contenir que les portées OAuth auxquelles un accès a été accordé. Dans cet exemple, seul myactivity.search a été accordé. Si vous incluez des groupes de ressources supplémentaires, une erreur est renvoyée. Pour en savoir plus, consultez la section Restrictions de champ d'application.

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 l'accès basé sur le temps, vous verrez les éléments suivants:
```
{
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
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.
```
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.

Remarque :Le temps nécessaire pour effectuer la tâche d'archivage dépend de la taille de l'archive. La durée maximale est de sept jours.

Si vous recevez un état FAILED dans la réponse, vous pouvez réessayer l'exportation à l'aide de la méthode RetryPortabilityArchive.

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 vous avez déjà exporté la ressource myactivity.search et un code temporel indiquant quand vous pouvez réessayer.

...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

Au bout de 24 heures, vous pouvez demander une nouvelle exportation, mais vous devez d'abord échanger votre jeton d'actualisation contre un nouveau jeton d'accès.
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'
```
La réponse doit se présenter comme suit:
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}
```
Si l'utilisateur renouvelle l'accès, le nouveau délai d'expiration est reflété dans le champ refresh_token_expires_in.

Vous pouvez utiliser le nouveau jeton d'accès pour répéter les étapes InitiatePortabilityArchive et GetPortabilityArchiveState.