Utilizzare le operazioni a lunga esecuzione in Cloud Storage

Questa pagina descrive come utilizzare le operazioni di lunga durata che vengono avviate dall'utilizzo di chiamate di metodi in Cloud Storage. Per informazioni dettagliate sulla semantica di un'operazione a lunga esecuzione restituita da una chiamata di metodo specifica, consulta la documentazione specifica della funzionalità.

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per gestire le operazioni di lunga durata in Cloud Storage, chiedi all'amministratore di concederti il ruolo Storage Admin (roles/storage.admin) o Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner) nel bucket o nel progetto utilizzato per eseguire l'operazione sottostante.

Questi ruoli predefiniti contengono le seguenti autorizzazioni, necessarie per gestire le operazioni di lunga durata in Cloud Storage:

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

Per informazioni sulla concessione dei ruoli sui bucket, consulta Impostare e gestire le policy IAM sui bucket. Per informazioni sulla concessione dei ruoli nei progetti, consulta Gestire l'accesso.

Visualizzare i dettagli di un'operazione a lunga esecuzione

Riga di comando

Per ottenere i dettagli o controllare lo stato di un'operazione a lunga esecuzione, utilizza il comando gcloud storage operations describe:

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

Sostituisci:

  • BUCKET_NAME con il nome del bucket che contiene l'operazione a lunga esecuzione. Ad esempio, my-bucket.

  • OPERATION_ID con l'ID dell'operazione a lunga esecuzione, che viene restituito nella risposta dei metodi che chiami. Ad esempio, la seguente risposta viene restituita dalla chiamata di gcloud storage restore e l'ID operazione a lunga esecuzione è BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

API REST

API JSON

  1. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con una richiesta 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"

    Sostituisci:

    • BUCKET_NAME con il nome del bucket associato all'operazione a lunga esecuzione.

    • OPERATION_ID con l'ID dell'operazione a lunga esecuzione, restituito nella risposta dei metodi che chiami. Ad esempio, la seguente risposta viene restituita dalla chiamata di gcloud storage restore e l'operazione a lunga esecuzione ha ID BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Se la richiesta ha esito positivo, viene restituita una risorsa operations:

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

Elenca le operazioni a lunga esecuzione in un bucket

Riga di comando

Per elencare le operazioni a lunga esecuzione in un bucket, utilizza il comando gcloud storage operations list:

gcloud storage operations list gs://BUCKET_NAME

Sostituisci:

  • BUCKET_NAME con il nome del bucket che contiene le operazioni a lunga esecuzione. Ad esempio, my-bucket.

API REST

API JSON

  1. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con una richiesta operations.get:

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

    Sostituisci:

    • BUCKET_NAME con il nome del bucket associato alle operazioni a lunga esecuzione che vuoi elencare.

Se la richiesta va a buon fine, riceverai una risposta simile alla seguente:

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

Annulla un'operazione a lunga esecuzione

Riga di comando

Per annullare un'operazione a lunga esecuzione, utilizza il comando gcloud storage operations cancel:

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

Sostituisci:

  • BUCKET_NAME con il nome del bucket che contiene l'operazione a lunga esecuzione. Ad esempio, my-bucket.

  • OPERATION_ID con l'ID dell'operazione a lunga esecuzione, che viene restituito nella risposta dei metodi che chiami. Ad esempio, la seguente risposta viene restituita dalla chiamata di gcloud storage restore e l'ID operazione a lunga esecuzione è BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

API REST

API JSON

  1. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con una richiesta 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"

    Sostituisci:

    • BUCKET_NAME con il nome del bucket associato all'operazione a lunga esecuzione che vuoi annullare.

    • OPERATION_ID con l'ID dell'operazione a lunga esecuzione, restituito nella risposta dei metodi che chiami. Ad esempio, la seguente risposta viene restituita dalla chiamata di gcloud storage restore e l'operazione a lunga esecuzione ha ID BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Metadati

Le operazioni a lunga esecuzione hanno metadati associati. I seguenti metadati identificano le proprietà di un'operazione a lunga esecuzione:

  • Ora di creazione: l'ora in cui è stata creata l'operazione a lunga esecuzione.

  • Ora di fine: l'ora in cui è terminata l'esecuzione dell'operazione a lunga esecuzione.

  • Ora aggiornamento: l'ora dell'ultima modifica dell'operazione a lunga esecuzione.

  • Tipo: il tipo di operazione a lunga esecuzione richiamata.

  • Annullamento richiesto: indica se l'utente ha richiesto l'annullamento dell'operazione a lunga esecuzione.

  • Percentuale di avanzamento: l'avanzamento stimato dell'operazione a lunga esecuzione, in percentuale. Un valore di -1 indica che lo stato di avanzamento è sconosciuto.

Gestione degli errori

Le operazioni a lunga esecuzione vengono avviate da API asincrone e richiedono pratiche di gestione degli errori diverse rispetto alle API sincrone. A differenza delle API sincrone, la risposta alle chiamate API asincrone può indicare l'esito positivo anche se l'operazione a lunga esecuzione alla fine non va a buon fine. Anziché fare affidamento sul codice di stato restituito nelle intestazioni della risposta, devi analizzare i metadati dell'operazione a lunga esecuzione nel corpo della risposta per determinare se una chiamata API è andata a buon fine.

Ad esempio, se effettui una richiesta di ripristino collettivo con eliminazione temporanea, viene restituito un codice di stato HTTP riuscito (200 OK) anche se si verifica un errore nel corso dell'operazione. Per verificare se l'operazione di ripristino collettivo è riuscita, ottieni lo stato dell'operazione a lunga esecuzione.

Tieni presente che le API per le operazione a lunga esecuzione (Get, List, Cancel) sono sincrone e restituiscono errori normali.