Utilizza 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 dettagli informazioni sulla semantica di un'operazione a lunga esecuzione che restituito da una specifica chiamata di metodo, consulta la documentazione specifica per la funzionalità.

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per gestire le operazioni a lunga esecuzione in Cloud Storage, chiedi all'amministratore di concederti il ruolo Amministratore Storage (roles/storage.admin) o il proprietario di bucket legacy di Storage (roles/storage.legacyBucketOwner) nel bucket o nel progetto utilizzata 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
di Gemini Advanced.

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

Visualizza i dettagli di un'operazione a lunga esecuzione

Riga di comando

Per conoscere i dettagli o controllare lo stato di un'operazione a lunga esecuzione, utilizza 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 del segmento di pubblico a lunga esecuzione che viene restituita nella risposta dei metodi chiamati. Per Ad esempio, la chiamata restituisce la seguente risposta gcloud storage restore e l'ID dell'operazione a lunga esecuzione è BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

API REST

API JSON

  1. Avere installato e inizializzato l'interfaccia a riga di comando gcloud, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con un 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 associate all'operazione a lunga esecuzione.

    • OPERATION_ID con l'ID dell'operazione a lunga esecuzione, restituito nella risposta dei metodi chiamati. Ad esempio, viene restituita la seguente risposta di chiamare gcloud storage restore e i pod a lunga esecuzione l'ID operazione è 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 la classe 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 installato e inizializzato, che consente generi un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con un 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. Per Ad esempio, la chiamata restituisce la seguente risposta 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 installato e inizializzato l'interfaccia a riga di comando gcloud, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con un 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 lungo termine da annullare.

    • OPERATION_ID con l'ID del a operazione a lunga esecuzione, che viene restituita nella risposta ai metodi che chiami. 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. Le seguenti I 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 è stata terminata l'esecuzione dell'operazione a lunga esecuzione.

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

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

  • Annullamento richiesto: indica se l'utente ha richiesto l'annullamento dell'operazione a lungo termine.

  • Percentuale di avanzamento: l'avanzamento stimato dell'operazione a lunga esecuzione. 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 delle operazioni a lungo termine 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 per le operazione a lunga esecuzione (Get, List, Cancel) sincrono e restituisce gli errori normali.