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

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 aux points de terminaison de l'API Data Portability.

Objectifs

Dans ce guide de démarrage rapide, vous allez apprendre à effectuer les tâches suivantes:

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 en utilisant les mêmes identifiants. Cette opération renvoie une erreur RESOURCE_EXHAUSTED et permet de mettre en évidence l'importance du point de terminaison ResetAuthorization.
Envoyez une requête authentifiée au point de terminaison ResetAuthorization. Cette requête révoque tous les champs d'application OAuth accordés par l'utilisateur.
(Facultatif) Envoyez une requête au point de terminaison InitiatePortabilityArchive à l'aide du même jeton OAuth que celui utilisé précédemment. La requête devrait é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 zone géographique. Pour obtenir la liste des pays et régions pris en charge, consultez les questions courantes de la page "Partager une copie de vos données avec un tiers".
Suivez la procédure de configuration de l'API Data Portability.
Suivez la procédure de configuration d'OAuth pour les applications Web JavaScript. En production, vous utiliserez normalement un flux différent, comme le flux OAuth pour les applications de serveur Web. Pour plus de simplicité, ce guide de démarrage rapide utilise le flux d'applications Web JavaScript.
- Lorsque vous créez vos identifiants d'autorisation, notez votre ID client OAuth 2.0 et l'URI de redirection autorisé (par exemple, https://google.com). Vous en aurez besoin dans la suite de ce guide de démarrage rapide.
- Lorsque vous configurez les 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.
Obtenez un jeton OAuth.
obtenir l'accès à un compte détenu 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 allez envoyer une requête d'autorisation afin d'obtenir un jeton OAuth à l'aide d'une URL. Ce processus utilise le flux des applications Web JavaScript. Ce flux ne renvoie pas de jeton d'actualisation.

Pour une application de production, vous utiliserez généralement un flux OAuth afin d'obtenir un jeton d'actualisation pouvant être utilisé pour générer des jetons d'accès à la demande. Le flux pour les applications Web côté serveur en est un exemple.

Pour obtenir un jeton OAuth:

Saisissez une URL comme suit :
```
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&
include_granted_scopes=true&
state=developer-specified-value
```
Dans l'URL:
- client_id est 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 celui de l'activité de recherche. Vous pouvez également utiliser la portée de l'activité YouTube ou les deux.
Collez l'URL dans la barre d'adresse de votre navigateur, puis suivez les étapes du flux OAuth. Cette procédure nécessite que vous vous connectiez au compte détenu ou contrôlé par votre organisation que vous utilisez pour ce guide de démarrage rapide.

Il s'agit du compte qui donne son autorisation pour les champs d'application OAuth. L'écran de consentement doit se présenter comme suit (le texte qui s'affiche peut être différent de celui de cette image):
Une fois l'autorisation accordée, vous devez ê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 l'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, <votre_jeton_OAuth> est une chaîne représentant le jeton.

Important :Votre jeton d'accès OAuth expire dans 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"
}

Rassemblez votre jeton OAuth et votre clé API. Vous en aurez besoin pour appeler 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:

Commencez par envoyer 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.
REMARQUE: Le paramètre resources ne doit contenir que les champs d'application OAuth auxquels l'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.

La requête InitiatePortabilityArchive renvoie job_id. Cet ID de job permet de récupérer l'état de l'archive de données.
```
{
  "archiveJobId": "<your_job_id>"
}
```
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.
```
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 tâche renvoyé par la requête InitiatePortabilityArchive.
La réponse est basée sur l'state 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'à la fin de la tâche.
```
{
  "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. Examinez le contenu de l'archive pour vous assurer qu'elle contient les données d'activité de recherche attendues.

Remarque :Le temps nécessaire à l'exécution du job d'archivage dépend de la taille de l'archive. La durée maximale est de sept jours.
Remarque :Si l'état FAILED apparaît dans la réponse, vous pouvez relancer l'exportation à l'aide de la méthode RetryPortabilityArchive.

(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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Envoyez une requête authentifiée au point de terminaison ResetAuthorization. Cette requête révoque tous les champs d'application OAuth accordés 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.

(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"
  }