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.

Appliquer des filtres temporels à vos requêtes

Dans ce guide de démarrage rapide, vous obtenez un jeton OAuth pour votre compte et vous envoyez des requêtes aux points de terminaison de l'API Data Portability à l'aide de codes temporels pour filtrer les données exportées.

Ce guide de démarrage rapide explique comment utiliser l'API Data Portability avec un accès basé sur le temps et appliquer des filtres temporels aux ressources compatibles. Pour en savoir plus sur l'accès basé sur le temps aux données utilisateur, consultez Utiliser l'accès basé sur le temps.

Objectifs

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

Envoyez des requêtes authentifiées récurrentes au point de terminaison InitiatePortabilityArchive pour n'exporter que les nouvelles données depuis votre dernière exportation.
Envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive pour n'exporter que les données des six derniers mois.
Envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive pour n'exporter que les données d'une période spécifique.

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, sélectionnez 30 jours pour tester le filtrage temporel avec un accès basé sur le temps. (Les filtres temporels fonctionnent également avec l'accès unique).
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:

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 utiliser tous les champs d'application compatibles avec les filtres temporels.

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. (Les filtres temporels fonctionnent également avec l'accès unique.)
Après avoir accordé votre consentement 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 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.

Important :Votre jeton d'accès OAuth expire au bout d'une heure. Si vous devez générer un nouveau jeton, suivez les étapes précédentes.
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 utiliserez des commandes curl pour appeler les points de terminaison de l'API Data Portability avec des codes temporels afin de filtrer les données exportées.Ces commandes nécessitent le jeton OAuth et la clé API que vous avez collectés précédemment.

Données de la dernière exportation

Vous pouvez utiliser des filtres temporels avec l'accès basé sur le temps pour exporter les nouvelles données depuis votre dernière exportation. Prenons l'exemple de la portée https://www.googleapis.com/auth/dataportability.myactivity.search.

Tout d'abord, vous envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive. Cette requête lance une tâche d'archivage pour l'ensemble complet des données.

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 niveaux d'accès OAuth qui ont été accordés et qui sont compatibles avec les filtres temporels. Dans cet exemple, seul myactivity.search a été accordé. Si vous incluez des groupes de ressources supplémentaires ou des groupes de ressources non compatibles, une erreur est renvoyée. Pour en savoir plus, consultez la section Restrictions de champ d'application.

La requête InitiatePortabilityArchive renvoie un archiveJobId 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_1>"
  "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_1/portabilityArchiveState
```
Dans la commande :
- your_OAuth_token est votre jeton OAuth.
- your_job_id_1 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. Il existe également un champ export_time qui représente l'horodatage du premier appel à InitiatePortabilityArchive.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
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.
Patientez au moins 24 heures, puis envoyez une autre requête à InitiatePortabilityArchive à l'aide de la même commande que celle de l'étape 1, mais cette fois, utilisez export_time comme start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Remarque :Vous pouvez ajuster start_time pour qu'il chevauche légèrement export_time afin de vous assurer que toutes les données générées entre les requêtes sont incluses dans l'exportation.

Pour l'accès basé sur le temps, les valeurs suivantes sont renvoyées:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Répétez l'étape 2 pour envoyer une requête authentifiée au point de terminaison GetPortabilityArchiveState afin de récupérer l'état de la tâche d'archivage (à l'aide de <your_job_id_2>).

Une fois la tâche terminée, la réponse est la suivante:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Vérifiez que les données de la deuxième exportation ne contiennent que les nouvelles données générées après la première exportation.

Données des six derniers mois

Vous pouvez également utiliser des filtres temporels pour n'exporter que les données les plus récentes au lieu du corpus complet.

Supposons que la date d'aujourd'hui soit le 2024-10-01 et que vous souhaitiez exporter les données des six derniers mois. Tout d'abord, vous envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive avec un start_time de "2024-04-01T00:00:00Z".

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"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Pour l'accès basé sur le temps, les valeurs suivantes sont renvoyées:
```
{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Envoyez une requête 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/job_id_1/portabilityArchiveState
```
Une fois la tâche terminée, la réponse est la suivante:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
Notez que start_time est le start_time spécifié à l'étape 1 et que export_time est le code temporel de l'appel à InitiatePortabilityArchive à l'étape 1.
Vérifiez que l'exportation ne contient que les données des six derniers mois.

Données d'une période spécifique

Vous pouvez utiliser des filtres temporels pour exporter des données d'une plage de dates spécifique, par exemple les données de 2023 uniquement.

Tout d'abord, vous envoyez une requête authentifiée au point de terminaison InitiatePortabilityArchive avec un start_time de "2023-01-01T00:00:00Z" et un end_time de "2023-12-31T23:59:59Z".

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"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Pour l'accès basé sur le temps, les valeurs suivantes sont renvoyées:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Envoyez une requête 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/job_id_1/portabilityArchiveState

Une fois la tâche terminée, la réponse est la suivante:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

Notez que start_time est le start_time spécifié à l'étape 1 et que export_time est égal à end_time fourni à l'étape 1.

Vérifiez que l'exportation ne contient que des données de 2023.

Champs d'application acceptés

Les champs d'application suivants sont compatibles avec les filtres temporels:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Attention:Les requêtes filtrées par date qui mélangent des portées compatibles et non compatibles génèrent une erreur INVALID_ARGUMENT indiquant The requested resources do not support time filters.