Utilizzare le operazioni a lunga esecuzione in Cloud Storage

Questa pagina descrive come utilizzare le operazioni a lungo termine avviate tramite le chiamate ai metodi in Cloud Storage. Per informazioni dettagliate sulla semantica di unoperazione 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 Amministratore Storage (roles/storage.admin) o Proprietario bucket legacy dello spazio di archiviazione (roles/storage.legacyBucketOwner) per il bucket o il progetto utilizzato per eseguire l'operazione sottostante.

Questi ruoli predefiniti contengono le seguenti autorizzazioni, obbligatorie per gestire le operazioni a lunga esecuzione in Cloud Storage:

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

Per informazioni sulla concessione dei ruoli ai bucket, consulta Utilizzare IAM con i bucket. Per informazioni sulla concessione di ruoli ai progetti, consulta Gestire l'accesso.

Visualizzare i dettagli di un'operazione a lunga esecuzione

Riga di comando

Per visualizzare 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 chiamati. Ad esempio, la chiamata a gcloud storage restore restituisce la seguente risposta 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 installato e inizializzatogcloud CLI, che 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 chiamati. Ad esempio, la seguente risposta viene restituita dalla chiamata a gcloud storage restore e l'ID operazione a lunga esecuzione è 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 installato e inizializzatogcloud CLI, che 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 ha esito positivo, viene visualizzata una risposta simile alla seguente:

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

Annullare 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 chiamati. Ad esempio, la chiamata a gcloud storage restore restituisce la seguente risposta 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 installato e inizializzatogcloud CLI, che 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 chiamati. Ad esempio, la seguente risposta viene restituita dalla chiamata a gcloud storage restore e l'ID operazione a lunga esecuzione è BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Metadati

Alle operazioni a lunga esecuzione sono associati metadati. 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 invocata.

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

  • Avanzamento in percentuale: l'avanzamento stimato dell'operazione a lunga esecuzione, expressed in percentuale. Un valore -1 indica che l'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 un esito positivo anche se l'operazione a lunga esecuzione non va a buon fine. Anziché fare affidamento sul codice di stato restituito nelle intestazioni di risposta, devi analizzare i metadati 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 soft, viene restituito un codice di stato HTTP di esito positivo (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 di operazione a lunga esecuzione (Get, List, Cancel) sono sincrone e restituiscono errori normali.