Usar operaciones de larga duración en Cloud Storage

En esta página se describe cómo usar las operaciones de larga duración que se inician mediante llamadas a métodos en Cloud Storage. Para obtener información detallada sobre la semántica de una operación de larga duración que se devuelve de una llamada a un método específico, consulta la documentación de la función.

Obtener los roles necesarios

Para obtener los permisos que necesitas para gestionar operaciones de larga duración en Cloud Storage, pide a tu administrador que te conceda el rol Administrador de Storage (roles/storage.admin) o el rol Propietario de segmento antiguo de Storage (roles/storage.legacyBucketOwner) en el segmento o el proyecto que se utilice para realizar la operación subyacente.

Estos roles predefinidos contienen los siguientes permisos, que son necesarios para gestionar operaciones de larga duración en Cloud Storage:

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

Nota: El usuario que inicia una operación de larga duración siempre puede obtener los detalles de la operación, independientemente de si tiene o no el permiso de gestión de identidades y accesos storage.bucketOperations.get. Los usuarios que no hayan iniciado la operación de larga duración deben tener el permiso storage.bucketOperations.get para obtener los detalles de la operación de larga duración. Los permisos storage.bucketOperations.list y storage.bucketOperations.cancel son necesarios para mostrar y cancelar operaciones de larga duración.

Para obtener información sobre cómo conceder roles en los contenedores, consulta Usar IAM con contenedores. Para obtener información sobre cómo conceder roles en proyectos, consulta el artículo Gestionar el acceso.

Obtener los detalles de una operación de larga duración

Línea de comandos

Nota: La CLI de Google Cloud especifica automáticamente un proyecto predeterminado, que se puede controlar con la marca --project.

Para obtener los detalles o comprobar el estado de una operación de larga duración, usa el comando gcloud storage operations describe:

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

Sustituye:

• BUCKET_NAME con el nombre del segmento que contiene la operación de larga duración. Por ejemplo, my-bucket.

• OPERATION_ID con el ID de la operación de larga duración, que se devuelve en la respuesta de los métodos que llames. Por ejemplo, la siguiente respuesta se devuelve al llamar a gcloud storage restore y el ID de operación de larga duración es BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

APIs REST

API JSON

1. Tener instalada e inicializadala CLI de gcloud, que te permite generar un token de acceso para el encabezado Authorization.

2. Usa cURL para llamar a la API JSON con una solicitud 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"

   Sustituye:

   • BUCKET_NAME con el nombre del contenedor asociado a la operación de larga duración.

   • OPERATION_ID con el ID de la operación de larga duración, que se devuelve en la respuesta de los métodos que llamas. Por ejemplo, la siguiente respuesta se devuelve al llamar a gcloud storage restore y el ID de la operación de larga duración es BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Si la solicitud se realiza correctamente, se devuelve un operationsrecurso:

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

Mostrar las operaciones de larga duración de un segmento

Línea de comandos

Para enumerar las operaciones de larga duración de un bucket, usa el comando gcloud storage operations list:

gcloud storage operations list gs://BUCKET_NAME

Sustituye:

• BUCKET_NAME con el nombre del segmento que contiene las operaciones de larga duración. Por ejemplo, my-bucket.

APIs REST

API JSON

1. Tener instalada e inicializadala CLI de gcloud, que te permite generar un token de acceso para el encabezado Authorization.

2. Usa cURL para llamar a la API JSON con una solicitud operations.get:

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

   Sustituye:

   • BUCKET_NAME con el nombre del contenedor asociado a las operaciones de larga duración que quieras enumerar.

Si la solicitud se realiza correctamente, obtendrás una respuesta similar a la siguiente:

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

Cancelar una operación de larga duración

Nota: La cancelación de una operación de larga duración es asíncrona y se hace de la mejor manera posible. Si se cancela una operación de larga duración en curso, se define el campo requested cancellation, pero no se garantiza que se respete la solicitud.

Línea de comandos

Nota: La CLI de Google Cloud especifica automáticamente un proyecto predeterminado, que se puede controlar con la marca --project.

Para cancelar una operación de larga duración, usa el comando gcloud storage operations cancel:

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

Sustituye:

• BUCKET_NAME con el nombre del segmento que contiene la operación de larga duración. Por ejemplo, my-bucket.

• OPERATION_ID con el ID de la operación de larga duración, que se devuelve en la respuesta de los métodos que llames. Por ejemplo, la siguiente respuesta se devuelve al llamar a gcloud storage restore y el ID de la operación de larga duración es BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

APIs REST

API JSON

1. Tener instalada e inicializadala CLI de gcloud, que te permite generar un token de acceso para el encabezado Authorization.

2. Usa cURL para llamar a la API JSON con una solicitud 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"

   Sustituye:

   • BUCKET_NAME con el nombre del contenedor asociado a la operación de larga duración que quieras cancelar.

   • OPERATION_ID con el ID de la operación de larga duración, que se devuelve en la respuesta de los métodos que llamas. Por ejemplo, la siguiente respuesta se devuelve al llamar a gcloud storage restore y el ID de la operación de larga duración es BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Metadatos

Las operaciones de larga duración tienen metadatos asociados. Los siguientes metadatos identifican las propiedades de una operación de larga duración:

• Create time (Hora de creación): hora en la que se creó la operación de larga duración.

• Hora de finalización: hora a la que ha terminado de ejecutarse la operación de larga duración.

• Hora de actualización: hora en la que se modificó por última vez la operación de larga duración.

• Tipo: el tipo de operación de larga duración invocada.

• Cancelación solicitada: indica si el usuario ha solicitado la cancelación de la operación de larga duración.

• Porcentaje de progreso: el progreso estimado de la operación de larga duración, en porcentaje. El valor -1 significa que se desconoce el progreso.

Gestión de errores

Las operaciones de larga duración se inician desde APIs asíncronas y requieren prácticas de gestión de errores diferentes a las de las APIs síncronas. A diferencia de las APIs síncronas, la respuesta a las llamadas a APIs asíncronas puede indicar que se han realizado correctamente aunque la operación de larga duración falle. En lugar de usar el código de estado que se devuelve en los encabezados de respuesta, debes analizar los metadatos de la operación de larga duración en el cuerpo de la respuesta para determinar si una llamada a la API se ha realizado correctamente.

Por ejemplo, si haces una solicitud de restauración masiva de eliminación lógica, devuelve un código de estado HTTP correcto (200 OK) aunque se produzca un error durante la operación. Para comprobar si la operación de restauración en bloque se ha completado correctamente, consulta el estado de la operación de larga duración.

Ten en cuenta que las APIs de operaciones de larga duración (Get, List y Cancel) son síncronas y devuelven errores normales.