Vorgänge mit langer Ausführungszeit in Cloud Storage verwenden

Auf dieser Seite wird beschrieben, wie Sie Vorgänge mit langer Ausführungszeit verwenden, die durch Methodenaufrufe in Cloud Storage initiiert werden. Ausführliche Informationen zur Semantik eines Vorgangs mit langer Ausführungszeit, der von einem bestimmten Methodenaufruf zurückgegeben wird, finden Sie in der funktionsspezifischen Dokumentation.

Erforderliche Rollen abrufen

Bitten Sie Ihren Administrator, Ihnen die Rolle „Storage-Administrator“ (roles/storage.admin) oder die Rolle „Storage Legacy Bucket Owner“ (roles/storage.legacyBucketOwner) für den Bucket oder das Projekt zuzuweisen, mit dem der zugrunde liegende Vorgang ausgeführt wird, um die Berechtigungen zu erhalten, die Sie zum Verwalten langwieriger Vorgänge in Cloud Storage benötigen.

Diese vordefinierten Rollen enthalten die folgenden Berechtigungen, die zum Verwalten lang laufender Vorgänge in Cloud Storage erforderlich sind:

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

Hinweis: Der Nutzer, der einen Vorgang mit langer Ausführungszeit initiiert, kann jederzeit die Details dazu abrufen, unabhängig davon, ob er die IAM-Berechtigung storage.bucketOperations.get hat. Nutzer, die den lang andauernden Vorgang nicht initiiert haben, benötigen die storage.bucketOperations.get, um die Details des Vorgangs abrufen zu können. Die Berechtigungen storage.bucketOperations.list und storage.bucketOperations.cancel sind immer erforderlich, um lang andauernde Vorgänge aufzulisten und abzubrechen.

Informationen zum Zuweisen von Rollen für Buckets finden Sie unter IAM mit Buckets verwenden. Informationen zum Zuweisen von Rollen für Projekte finden Sie unter Zugriff verwalten.

Details eines Vorgangs mit langer Ausführungszeit abrufen

Befehlszeile

Hinweis: Die Google Cloud CLI gibt automatisch ein Standardprojekt an, das mit dem Flag --project gesteuert werden kann.

Mit dem Befehl gcloud storage operations describe können Sie Details zu einem Vorgang mit langer Ausführungszeit abrufen oder den Status prüfen:

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

Ersetzen Sie:

• BUCKET_NAME durch den Namen des Buckets, der den Vorgang mit langer Ausführungszeit enthält. Beispiel: my-bucket.

• OPERATION_ID durch die ID des lang andauernden Vorgangs, der in der Antwort der von Ihnen aufgerufenen Methoden zurückgegeben wird. Beispielsweise wird beim Aufrufen von gcloud storage restore die folgende Antwort zurückgegeben und die ID des Vorgangs mit langer Ausführungszeit lautet BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

REST APIs

JSON API

1. Installieren und initialisieren Sie die dcloud CLI, um ein Zugriffstoken für den Header Authorization zu generieren.

   Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.

2. Verwenden Sie cURL, um die JSON API mit einer operations.get-ReportConfig-Anfrage aufzurufen:

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

   Ersetzen Sie:

   • BUCKET_NAME durch den Namen des Buckets, der mit dem Vorgang mit langer Ausführungszeit verknüpft ist.

   • OPERATION_ID durch die ID des Vorgangs mit langer Ausführungszeit ersetzen, die in der Antwort der von Ihnen aufgerufenen Methoden zurückgegeben wird. Beispielsweise wird beim Aufrufen von gcloud storage restore die folgende Antwort zurückgegeben und die ID des Vorgangs mit langer Ausführungszeit lautet BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Wenn die Anfrage erfolgreich ist, wird eine operations-Ressource zurückgegeben:

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

Vorgänge mit langer Ausführungszeit in einem Bucket auflisten

Befehlszeile

Um die Vorgänge mit langer Ausführungszeit in einem Bucket aufzulisten, verwenden Sie den gcloud storage operations list-Befehl:

gcloud storage operations list gs://BUCKET_NAME

Ersetzen Sie:

• BUCKET_NAME durch den Namen des Buckets, der die Vorgänge mit langer Ausführungszeit enthält. Beispiel: my-bucket.

REST APIs

JSON API

1. Installieren und initialisieren Sie die dcloud CLI, um ein Zugriffstoken für den Header Authorization zu generieren.

   Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.

2. Verwenden Sie cURL, um die JSON API mit einer operations.get-ReportConfig-Anfrage aufzurufen:

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

   Ersetzen Sie:

   • BUCKET_NAME durch den Namen des Buckets, der mit den Vorgängen mit langer Ausführungszeit verknüpft ist, die Sie auflisten möchten.

Wenn die Anfrage erfolgreich ist, erhalten Sie eine Antwort ähnlich der folgenden:

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

Lange laufenden Vorgang abbrechen

Hinweis: Das Abbrechen eines Vorgangs mit langer Ausführungszeit erfolgt asynchron und nach bestem Gewissen. Durch eine Abbruchanfrage für einen laufenden Vorgang mit langer Ausführungszeit wird das Feld requested cancellation festgelegt, aber es gibt keine Garantie, dass die Anfrage erfüllt wird.

Befehlszeile

Hinweis: Die Google Cloud CLI gibt automatisch ein Standardprojekt an, das mit dem Flag --project gesteuert werden kann.

Verwenden Sie den Befehl gcloud storage operations cancel, um einen langwierigen Vorgang abzubrechen:

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

Ersetzen Sie:

• BUCKET_NAME durch den Namen des Buckets, der den Vorgang mit langer Ausführungszeit enthält. Beispiel: my-bucket.

• OPERATION_ID durch die ID des lang andauernden Vorgangs, der in der Antwort der von Ihnen aufgerufenen Methoden zurückgegeben wird. Beispielsweise wird beim Aufrufen von gcloud storage restore die folgende Antwort zurückgegeben und die ID des Vorgangs mit langer Ausführungszeit lautet BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

REST APIs

JSON API

1. Installieren und initialisieren Sie die dcloud CLI, um ein Zugriffstoken für den Header Authorization zu generieren.

   Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.

2. Verwenden Sie cURL, um die JSON API mit einer operations.post-ReportConfig-Anfrage aufzurufen:

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

   Ersetzen Sie:

   • BUCKET_NAME durch den Namen des Buckets, der mit dem Vorgang mit langer Ausführungszeit verknüpft ist, den Sie abbrechen möchten.

   • OPERATION_ID durch die ID des Vorgangs mit langer Ausführungszeit ersetzen, die in der Antwort der von Ihnen aufgerufenen Methoden zurückgegeben wird. Beispielsweise wird beim Aufrufen von gcloud storage restore die folgende Antwort zurückgegeben und die ID des Vorgangs mit langer Ausführungszeit lautet BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Metadaten

Langlaufende Vorgänge sind mit Metadaten verknüpft. Die folgenden Metadaten geben Eigenschaften eines Vorgangs mit langer Ausführungszeit an:

• Erstellungszeit: Die Zeit, zu der der Vorgang mit langer Ausführungszeit erstellt wurde.

• Endzeit: Der Zeitpunkt, zu dem der Vorgang mit langer Ausführungszeit abgeschlossen wurde.

• Aktualisierungszeit: Die Uhrzeit, zu der der langlaufende Vorgang zuletzt geändert wurde.

• Typ: Der Typ des aufgerufenen Vorgangs mit langer Ausführungszeit.

• Abbruch angefordert: Gibt an, ob der Nutzer den Abbruch des lang andauernden Vorgangs angefordert hat.

• Prozentsatz des Fortschritts: Der geschätzte Fortschritt des Vorgangs mit langer Ausführungszeit in Prozent. Der Wert -1 bedeutet, dass der Fortschritt unbekannt ist.

Fehlerbehandlung

Vorgänge mit langer Ausführungszeit werden von asynchronen APIs initiiert und erfordern eine andere Fehlerbehandlung als synchrone APIs. Im Gegensatz zu synchronen APIs kann die Antwort auf asynchrone API-Aufrufe auch dann erfolgreich sein, wenn der Vorgang mit langer Ausführungszeit schließlich fehlschlägt. Anstatt sich auf den Statuscode zu verlassen, der in den Antwort-Headern zurückgegeben wird, sollten Sie die Metadaten des Vorgangs mit langer Ausführungszeit im Text der Antwort parsen, um festzustellen, ob ein API-Aufruf erfolgreich war.

Wenn Sie beispielsweise eine Bulk-Wiederherstellungsanfrage für vorläufiges Löschen stellen, wird ein erfolgreicher HTTP-Statuscode (200 OK) zurückgegeben, auch wenn während des Vorgangs ein Fehler auftritt. Um zu prüfen, ob der Bulk-Wiederherstellungsvorgang erfolgreich war, fragen Sie den Status des Vorgangs mit langer Ausführungszeit ab.

Beachten Sie, dass die APIs für Vorgänge mit langer Ausführungszeit (Get, List, Cancel) synchron sind und normale Fehler zurückgeben.