Gérer les opérations de longue durée

Une opération de longue durée (LRO) est une méthode d'API qui prend plus de temps à s'exécuter que ce qui est approprié pour une réponse d'API. En règle générale, vous ne souhaitez pas maintenir le thread d'appel ouvert pendant l'exécution de la tâche, car cela offre une mauvaise expérience utilisateur. Il est préférable de renvoyer un type de promesse à l'utilisateur et de lui permettre de revenir plus tard.

L'API Google Drive renvoie une opération de longue durée chaque fois que vous appelez la méthode download() sur la ressource files pour télécharger le contenu d'un fichier via l'API Drive ou ses bibliothèques clientes.

La méthode renvoie une ressource operations au client. Vous pouvez utiliser la ressource operations pour récupérer de manière asynchrone l'état de la méthode de l'API en interrogeant l'opération via la méthode get(). Les opérations de longue durée de l'API Drive respectent le modèle de conception des opérations de longue durée Google Cloud.

Pour en savoir plus, consultez la section Opérations de longue durée.

Présentation du processus

Le schéma suivant illustre les étapes générales du fonctionnement de la méthode file.download.

Étapes générales de la méthode file.download.
Figure 1. Étapes générales de la méthode file.download.

  1. Appeler files.download: lorsque votre application appelle la méthode download(), elle lance la requête de téléchargement de l'API Drive pour le fichier. Pour en savoir plus, consultez Télécharger des fichiers.

  2. Demander des autorisations: la requête envoie des identifiants d'authentification à l'API Drive. Si votre application nécessite d'appeler l'API Drive à l'aide de l'authentification d'un utilisateur qui n'a pas encore été accordée, elle invite l'utilisateur à se connecter. Votre application demande également l'accès avec les champs d'application que vous spécifiez lors de la configuration de l'authentification.

  3. Démarrer le téléchargement: une requête API Drive est envoyée pour démarrer le téléchargement du fichier. La demande peut concerner Google Vids ou un autre contenu Google Workspace.

  4. Démarrer l'opération de longue durée: une opération de longue durée commence et gère le processus de téléchargement.

  5. Renvoyer une opération en attente: l'API Drive renvoie une opération en attente contenant des informations sur l'utilisateur qui envoie la requête et plusieurs champs de métadonnées de fichier.

  6. État d'attente initial: votre application reçoit l'opération en attente avec un état d'attente initial de done=null. Cela signifie que le fichier n'est pas encore prêt à être téléchargé et que l'état de l'opération est en attente.

  7. Appeler operations.get et vérifier le résultat: votre application appelle get() aux intervalles recommandés pour interroger le résultat de l'opération et obtenir le dernier état d'une opération de longue durée. Si l'état en attente de done=false est renvoyé, votre application doit continuer à interroger l'opération jusqu'à ce qu'elle renvoie l'état terminée (done=true). Pour les fichiers volumineux, attendez-vous à effectuer plusieurs requêtes. Pour en savoir plus, consultez Obtenir les détails d'une opération de longue durée.

  8. Vérifier l'état en attente: si l'état en attente de done=true est renvoyé par la LRO, cela signifie que le fichier est prêt à être téléchargé et que l'état de l'opération est terminé.

  9. Renvoyer l'opération terminée avec l'URI de téléchargement: une fois l'opération de longue durée terminée, l'API Drive renvoie l'URI de téléchargement et le fichier est désormais disponible pour l'utilisateur.

Télécharger des fichiers

Pour télécharger du contenu dans le cadre d'une opération de longue durée, utilisez la méthode download() sur la ressource files. La méthode utilise les paramètres de requête file_id, mime_type et revision_id:

  • Obligatoire. Le paramètre de requête file_id correspond à l'ID du fichier à télécharger.

  • Facultatif. Le paramètre de requête mime_type indique le type MIME que la méthode doit utiliser. Elle n'est disponible que lors du téléchargement de contenus multimédias autres que des objets blob (par exemple, des documents Google Workspace). Pour obtenir la liste complète des types MIME compatibles, consultez Exporter des types MIME pour les documents Google Workspace.

    Si le type MIME n'est pas défini, le document Google Workspace est téléchargé avec un type MIME par défaut. Pour en savoir plus, consultez Types MIME par défaut.

  • Facultatif. Le paramètre de requête revision_id correspond à l'ID de révision du fichier à télécharger. Elle n'est disponible que pour le téléchargement de fichiers blob, de Google Docs et de Google Sheets. Renvoie le code d'erreur INVALID_ARGUMENT lors du téléchargement d'une révision spécifique sur des fichiers non compatibles.

La méthode download() est le seul moyen de télécharger des fichiers Vids au format MP4. Elle est généralement la plus adaptée pour télécharger la plupart des fichiers vidéo.

Les liens de téléchargement générés pour Google Docs ou Sheets renvoient initialement une redirection. Cliquez sur le nouveau lien pour télécharger le fichier.

Une requête à la méthode download() qui lance l'opération de longue durée et la requête permettant d'extraire l'URI de téléchargement final doivent toutes deux utiliser des clés de ressource. Pour en savoir plus, consultez Accéder aux fichiers Drive partagés par lien à l'aide de clés de ressources.

Le protocole de requête est affiché ici.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Remplacez FILE_ID par le fileId du fichier que vous souhaitez télécharger.

Types MIME par défaut

Si aucun type MIME n'est défini lors du téléchargement de contenu autre qu'un blob, les types MIME par défaut suivants sont attribués:

Type de document Format type MIME Extension de fichier
Google Apps Script JSON application/vnd.google-apps.script+json .json
Google Docs Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
Google Drawings PNG image/png .png
Google Forms ZIP application/zip .zip
Google Sheets Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx
Google Sites Texte brut text/raw .txt
Google Slides Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
Google Vids MP4 application/mp4 .mp4
Jamboard PDF application/pdf .pdf

Télécharger la réponse

Lorsque vous appelez la méthode download(), le corps de la réponse consiste en une ressource représentant une opération de longue durée. La méthode renvoie généralement un lien permettant de télécharger le contenu du fichier.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Ce résultat inclut les valeurs suivantes :

Notez que le champ partialDownloadAllowed indique si un téléchargement partiel est autorisé. "True" (Vrai) lors du téléchargement du contenu du fichier blob.

Obtenir les détails d'une opération de longue durée

Les opérations de longue durée sont des appels de méthode dont l'exécution peut prendre un temps considérable. En règle générale, les opérations de téléchargement nouvellement créées sont initialement renvoyées dans un état en attente (done=null), en particulier pour les fichiers Vids.

Vous pouvez utiliser la ressource operations fournie par l'API Drive pour vérifier l'état de l'opération de longue durée de traitement en incluant le nom unique attribué par le serveur.

La méthode get() obtient de manière asynchrone le dernier état d'une opération de longue durée. Cette méthode permet aux clients d'interroger le résultat de l'opération à des intervalles recommandés par le service d'API.

Interroger une opération de longue durée

Pour interroger une opération de longue durée disponible, appelez de façon répétée la méthode get() jusqu'à la fin de l'opération. Utilisez un intervalle exponentiel entre les tentatives entre chaque tentative d'interrogation (10 secondes, par exemple).

Une LRO reste disponible pendant au moins 12 heures, mais peut parfois persister plus longtemps. Cette durée est susceptible d'être modifiée et peut varier selon les types de fichiers. Une fois la ressource arrivée à expiration, une nouvelle requête de méthode download() est nécessaire.

Toutes les requêtes envoyées à get() doivent utiliser des clés de ressource. Pour en savoir plus, consultez la section Accéder aux fichiers Drive partagés par lien à l'aide de clés de ressource.

Les protocoles de requête sont affichés ici.

Appel de méthode

operations.get(name='NAME');

Remplacez NAME par le nom attribué par le serveur à l'opération, comme indiqué dans la réponse à la requête de méthode download().

curl

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Remplacez NAME par le nom attribué par le serveur à l'opération, comme indiqué dans la réponse à la requête de méthode download().

La commande utilise le chemin d'accès /drive/v3/operations/NAME.

Notez que name n'est renvoyé que dans la réponse à une requête download(). Il n'existe aucun autre moyen de le récupérer, car l'API Drive n'est pas compatible avec la méthode List(). Si la valeur name est perdue, vous devez générer une nouvelle réponse en appelant à nouveau la requête de la méthode download().

La réponse d'une requête get() se compose d'une ressource représentant une opération de longue durée. Pour en savoir plus, consultez la section Télécharger la réponse.

Lorsque la réponse contient un état terminé (done=true), l'opération de longue durée est terminée.

Télécharger une révision

Vous pouvez utiliser la valeur du champ headRevisionId de la ressource files pour télécharger la dernière révision. Cette opération récupère la révision qui correspond aux métadonnées du fichier que vous avez précédemment récupéré. Pour télécharger les données de toutes les révisions précédentes du fichier qui sont toujours stockées dans le cloud, vous pouvez appeler la méthode list() sur la ressource revisions avec le paramètre fileId. Cette commande renvoie tous les revisionIds du fichier.

Pour télécharger le contenu de la révision des fichiers blob, vous devez appeler la méthode get() sur la ressource revisions avec l'ID du fichier à télécharger, l'ID de la révision et le paramètre d'URL alt=media. Le paramètre d'URL alt=media indique au serveur qu'un téléchargement de contenu est demandé en tant que format de réponse alternatif.

Les révisions de Google Docs, Sheets, Slides et Vids ne peuvent pas être téléchargées à l'aide de la méthode get() avec l'URL alt=media . Sinon, il génère une erreur fileNotDownloadable.

Le paramètre d'URL alt=media est un paramètre système disponible dans toutes les API REST Google. Si vous utilisez une bibliothèque cliente pour l'API Drive, vous n'avez pas besoin de définir explicitement ce paramètre.

Le protocole de requête est affiché ici.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Remplacez les éléments suivants :

  • FILE_ID: fileId du fichier que vous souhaitez télécharger.
  • REVISION_ID: revisionId de la révision que vous souhaitez télécharger.

Les révisions de Google Docs, Drawings et Slides incrémentent automatiquement les numéros de révision. Toutefois, la série de nombres peut comporter des lacunes si des révisions sont supprimées. Par conséquent, vous ne devez pas vous fier aux numéros séquentiels pour récupérer les révisions.

Résoudre les problèmes liés aux LRO

Lorsqu'une opération de longue durée échoue, sa réponse inclut un code d'erreur canonique Google Cloud.

Le tableau suivant explique la cause de chaque code et fournit une recommandation pour le gérer. Pour de nombreuses erreurs, l'action recommandée consiste à réessayer la requête à l'aide d'un intervalle exponentiel entre les tentatives.

Pour en savoir plus sur ce modèle d'erreur et sur son utilisation, consultez le Guide de conception d'API.

Code Énumération Description Action recommandée
1 CANCELLED L'opération a été annulée, généralement par l'appelant. Réexécutez l'opération.
2 UNKNOWN Cette erreur peut s'afficher lorsqu'une valeur Status reçue d'un autre espace d'adressage appartient à un espace d'erreur inconnu dans cet espace d'adressage. Si l'erreur de l'API ne renvoie pas suffisamment d'informations, elle peut être convertie en cette erreur. Réessayer avec un intervalle exponentiel entre les tentatives
3 INVALID_ARGUMENT Le client a spécifié un argument non valide. Cette erreur diffère de FAILED_PRECONDITION. INVALID_ARGUMENT indique les arguments problématiques quel que soit l'état du système (par exemple, un nom de fichier mal formé). Ne relancez pas la requête avant d'avoir résolu le problème.
4 DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Pour les opérations qui modifient l'état du système, cette erreur peut être renvoyée même si l'opération s'est terminée avec succès. Par exemple, une réponse réussie d'un serveur aurait pu être retardée suffisamment longtemps pour que le délai expire. Réessayer avec un intervalle exponentiel entre les tentatives
5 NOT_FOUND Une entité demandée (par exemple, une ressource FHIR) est introuvable. Ne relancez pas la requête avant d'avoir résolu le problème.
6 ALREADY_EXISTS L'entité qu'un client a tenté de créer (par exemple, une instance DICOM) existe déjà. Ne relancez pas la requête avant d'avoir résolu le problème.
7 PERMISSION_DENIED L'appelant n'est pas autorisé à exécuter l'opération spécifiée. Ce code d'erreur n'implique pas que la requête soit valide, que l'entité demandée existe ou qu'elle réponde à d'autres prérequis. Ne relancez pas la requête avant d'avoir résolu le problème.
8 RESOURCE_EXHAUSTED Une ressource a été épuisée, par exemple un quota par projet. Réessayer avec un intervalle exponentiel entre les tentatives Des quotas peuvent être disponibles au fil du temps.
9 FAILED_PRECONDITION L'opération a été rejetée car le système n'est pas dans un état requis pour exécuter l'opération. Par exemple, le répertoire à supprimer n'est pas vide ou une opération rmdir est appliquée à un emplacement qui n'est pas un répertoire. Ne relancez pas la requête avant d'avoir résolu le problème.
10 ABORTED L'opération a été abandonnée, généralement en raison d'un problème de simultanéité, tel qu'un échec de vérification du séquenceur ou un abandon de transaction. Réessayer avec un intervalle exponentiel entre les tentatives
11 OUT_OF_RANGE L'opération a été tentée au-delà de la plage valide (par exemple, rechercher ou lire après la fin du fichier). Contrairement à INVALID_ARGUMENT, cette erreur indique un problème pouvant être résolu si l'état du système change. Ne relancez pas la requête avant d'avoir résolu le problème.
12 UNIMPLEMENTED L'opération n'est pas implémentée ou n'est pas prise en charge/activée dans l'API Drive. Ne pas réessayer.
13 INTERNAL Erreurs internes. Cela indique qu'une erreur inattendue s'est produite lors du traitement dans le système sous-jacent. Réessayer avec un intervalle exponentiel entre les tentatives
14 UNAVAILABLE L'API Drive n'est pas disponible. Il s'agit probablement d'une condition temporaire qui peut être corrigée en réessayant avec un intervalle exponentiel entre les tentatives. Notez qu'il n'est pas toujours sûr de relancer des opérations non idempotentes. Réessayer avec un intervalle exponentiel entre les tentatives
15 DATA_LOSS Perte ou corruption de données irrécupérable. Contactez votre administrateur système. L'administrateur système peut contacter un représentant de l'assistance en cas de perte ou de corruption de données.
16 UNAUTHENTICATED La requête ne dispose pas d'identifiants d'authentification valides pour l'opération. Ne relancez pas la requête avant d'avoir résolu le problème.