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

Une opération de longue durée est une méthode d'API dont l'exécution prend plus de temps que ce qui est approprié pour une réponse d'API. En règle générale, vous ne souhaitez pas maintenir le thread appelant 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 files ressource 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 d'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 de Google Cloud pattern.

Pour en savoir plus, consultez la page 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.

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 d'une authentification 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 d'API Drive est envoyée pour démarrer le téléchargement du fichier. La requête peut être adressée à 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 l'opération en attente : l'API Drive renvoie une opération en attente contenant des informations sur l'utilisateur qui effectue la requête et plusieurs champs de métadonnées de fichier.

6. État initial en attente : votre application reçoit l'opération en attente avec un état initial en attente done=null. Cela indique 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 done=false est renvoyé, votre application doit continuer à interroger jusqu'à ce que l'opération renvoie l'état terminé (done=true). Pour les fichiers volumineux, prévoyez d'interroger plusieurs fois. 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 done=true est renvoyé par l'opération de longue durée, cela indique 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 download méthode sur la files ressource. La méthode prend les paramètres file_id, mime_type et revision_id :

• Obligatoire. Le paramètre de chemin d'accès 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. Il n'est disponible que lors du téléchargement de contenu multimédia non blob (tel que des documents Google Workspace). Pour obtenir la liste complète des types MIME compatibles, consultez Types MIME d'exportation 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. Il n'est disponible que lors du téléchargement de fichiers blob, Google Docs et 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 et est généralement la plus adaptée au téléchargement de la plupart des fichiers vidéo. Si vous tentez d'exporter des fichiers Google Vids, vous recevez une fileNotExportable erreur.

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 adressée à la méthode download qui lance l'opération de longue durée et la requête permettant de récupérer 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 ressource.

Le protocole de requête est indiqué 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.

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

operations.get(name='NAME');

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

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