Utiliser des opérations de longue durée dans Cloud Storage

Cette page explique comment utiliser les opérations de longue durée lancées à l'aide d'appels de méthode dans Cloud Storage. Pour plus d'informations sur la sémantique d'une opération de longue durée renvoyée par un appel de méthode spécifique, consultez la documentation spécifique à la fonctionnalité.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour gérer les opérations de longue durée dans Cloud Storage, demandez à votre administrateur de vous accorder le rôle "Administrateur de l'espace de stockage" (roles/storage.admin) ou le rôle "Propriétaire des anciens buckets Storage" (roles/storage.legacyBucketOwner) sur le bucket ou le projet utilisé pour effectuer l'opération sous-jacente.

Ces rôles prédéfinis contiennent les autorisations suivantes, requises pour gérer les opérations de longue durée dans Cloud Storage :

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list

Pour en savoir plus sur l'attribution de rôles dans des buckets, consultez la page Utiliser IAM avec des buckets. Pour savoir comment attribuer des rôles aux projets, consultez la page Gérer l'accès.

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

Ligne de commande

Pour obtenir des détails ou vérifier l'état d'une opération de longue durée, utilisez la commande gcloud storage operations describe:

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Remplacez :

  • BUCKET_NAME : nom du bucket contenant l'opération de longue durée. Exemple :my-bucket

  • OPERATION_ID par l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de gcloud storage restore, et l'ID de l'opération de longue durée est BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP :

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLI, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

  2. Utilisez cURL pour appeler l'API JSON avec une requête operations.get:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"

    Remplacez :

    • BUCKET_NAME par le nom du bucket associé à l'opération de longue durée.

    • OPERATION_ID par l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de gcloud storage restore, et l'ID de l'opération de longue durée est BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP :

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

Si la requête aboutit, une ressource operations est renvoyée :

{
  "kind": "storage#operation",
  "name": "projects/_/buckets/bucket/operations/operation_id",
  "metadata": {
    "@type": OperationMetadataType*,
    metadata OperationMetadata*
  },
  "done": boolean,
  "response": {
    "@type": ResponseResourceType*,
    response ResponseResource*
  }
}

Lister les opérations de longue durée dans un bucket

Ligne de commande

Pour répertorier les opérations de longue durée dans un bucket, utilisez la commande gcloud storage operations list:

gcloud storage operations list gs://BUCKET_NAME

Remplacez :

  • BUCKET_NAME par le nom du bucket contenant les opérations de longue durée. Exemple :my-bucket

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLI, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

  2. Utilisez cURL pour appeler l'API JSON avec une requête operations.get:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"

    Remplacez :

    • BUCKET_NAME par le nom du bucket associé aux opérations de longue durée que vous souhaitez répertorier.

Si la requête aboutit, vous obtenez une réponse semblable à celle-ci :

{
  "kind": "storage#operations",
  "nextPageToken": string,
  "operations": [
    operations Resource
  ]
}

Annuler une opération de longue durée

Ligne de commande

Pour annuler une opération de longue durée, utilisez la commande gcloud storage operations cancel:

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Remplacez :

  • BUCKET_NAME : nom du bucket contenant l'opération de longue durée. Exemple :my-bucket

  • OPERATION_ID par l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de gcloud storage restore, et l'ID de l'opération de longue durée est BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP :

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLI, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

  2. Utilisez cURL pour appeler l'API JSON avec une requête operations.post:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

    Remplacez :

    • BUCKET_NAME par le nom du bucket associé à l'opération de longue durée que vous souhaitez annuler.

    • OPERATION_ID par l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de gcloud storage restore, et l'ID de l'opération de longue durée est BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP :

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

Métadonnées

Les opérations de longue durée comportent des métadonnées associées. Les métadonnées suivantes identifient les propriétés d'une opération de longue durée :

  • Heure de création : heure à laquelle l'opération de longue durée a été créée.

  • Heure de fin : heure à laquelle l'exécution de l'opération de longue durée s'est terminée.

  • Heure de mise à jour : heure de la dernière modification de l'opération de longue durée.

  • Type : type d'opération de longue durée appelée.

  • Annulation demandée : indique si l'utilisateur a demandé l'annulation de l'opération de longue durée.

  • Pourcentage de progression : progression estimée de l'opération de longue durée, en pourcentage. Une valeur -1 signifie que la progression est inconnue.

Gestion des exceptions

Les opérations de longue durée sont lancées à partir d'API asynchrones et nécessitent des pratiques de gestion des exceptions différentes de celles des API synchrones. Contrairement aux API synchrones, la réponse aux appels d'API asynchrones peut indiquer un succès même si l'opération de longue durée échoue. Au lieu de vous fier au code d'état renvoyé dans les en-têtes de réponse, vous devez analyser les métadonnées de l'opération de longue durée dans le corps de la réponse pour déterminer si un appel d'API a réussi.

Par exemple, si vous effectuez une requête de restauration groupée portant sur des objets soumis à suppression réversible, elle renvoie un code d'état HTTP positif (200 OK), même si une erreur se produit au cours de l'opération. Pour vérifier si l'opération de restauration groupée a réussi, interrogez l'état de l'opération de longue durée.

Notez que les API qui renvoient des opérations de longue durée (Get, List, Cancel) sont synchrones et renvoient des erreurs normales.