Vorgänge mit langer Ausführungszeit verwalten

Ein Vorgang mit langer Ausführungszeit (Long-Running Operation, LRO) ist eine API-Methode, deren Ausführung länger dauert als für eine API-Antwort angemessen ist. Normalerweise sollten Sie den Aufruf-Thread nicht geöffnet lassen, während die Aufgabe ausgeführt wird, da dies die Nutzerfreundlichkeit beeinträchtigt. Stattdessen sollten Sie dem Nutzer eine Art Versprechen machen und ihm die Möglichkeit geben, später noch einmal nachzufragen.

Die Google Drive API gibt jedes Mal einen LRO zurück, wenn Sie die Methode download() auf der Ressource files aufrufen, um den Inhalt einer Datei entweder über die Drive API oder ihre Clientbibliotheken herunterzuladen.

Die Methode gibt dem Client eine operations-Ressource zurück. Sie können die Ressource operations verwenden, um den Status der API-Methode asynchron abzurufen. Dazu wird der Vorgang über die Methode get() abgefragt. LROs in der Drive API folgen dem Google Cloud-Designmuster für LROs.

Weitere Informationen finden Sie unter Vorgänge mit langer Ausführungszeit.

Prozessübersicht

Das folgende Diagramm zeigt die allgemeinen Schritte der file.download-Methode.

Allgemeine Schritte für die Methode „file.download“.
Abbildung 1. Allgemeine Schritte für die Methode „file.download“.

  1. files.download aufrufen: Wenn Ihre App die Methode download() aufruft, wird die Drive API-Downloadanfrage für die Datei gestartet. Weitere Informationen finden Sie unter Dateien herunterladen.

  2. Berechtigungen anfordern: Bei der Anfrage werden Authentifizierungsdaten an die Drive API gesendet. Wenn für Ihre App die Drive API mit der Authentifizierung eines Nutzers aufgerufen werden muss, die noch nicht gewährt wurde, wird der Nutzer aufgefordert, sich anzumelden. Ihre App fordert auch Zugriff mit Umfängen an, die Sie bei der Einrichtung der Authentifizierung angeben.

  3. Download starten: Es wird eine Drive API-Anfrage gesendet, um den Dateidownload zu starten. Die Anfrage kann sich auf Google Vids oder andere Google Workspace-Inhalte beziehen.

  4. Start LRO (Vorgang mit langer Ausführungszeit starten): Ein Vorgang mit langer Ausführungszeit wird gestartet und verwaltet den Downloadvorgang.

  5. Ausstehenden Vorgang zurückgeben: Die Drive API gibt einen ausstehenden Vorgang zurück, der Informationen zum Nutzer enthält, der die Anfrage gestellt hat, sowie mehrere Dateimetadatenfelder.

  6. Ursprünglicher ausstehender Status: Ihre App empfängt den ausstehenden Vorgang zusammen mit einem ursprünglichen ausstehenden Status von done=null. Das bedeutet, dass die Datei noch nicht zum Download bereit ist und der Vorgangsstatus ausstehend ist.

  7. operations.get aufrufen und Ergebnis prüfen: Ihre App ruft get() in den empfohlenen Intervallen auf, um das Ergebnis des Vorgangs abzufragen und den aktuellen Status eines lang andauernden Vorgangs abzurufen. Wenn der Status „Ausstehend“ (done=false) zurückgegeben wird, muss Ihre App weiter abfragen, bis der Vorgang den Status „Abgeschlossen“ (done=true) zurückgibt. Bei großen Dateien ist es wahrscheinlich, dass mehrere Abfragen erforderlich sind. Weitere Informationen finden Sie unter Details zu einem lang andauernden Vorgang abrufen.

  8. Ausstehenden Status prüfen: Wenn der ausstehende Status done=true vom LRO zurückgegeben wird, ist die Datei zum Herunterladen bereit und der Vorgangsstatus ist abgeschlossen.

  9. Abgeschlossenen Vorgang mit Download-URI zurückgeben: Sobald der LRO abgeschlossen ist, gibt die Drive API den Download-URI zurück und die Datei ist jetzt für den Nutzer verfügbar.

Dateien herunterladen

Wenn Sie Inhalte während eines langwierigen Vorgangs herunterladen möchten, verwenden Sie die Methode download() für die Ressource files. Die Methode verwendet die Abfrageparameter file_id, mime_type und revision_id:

  • Erforderlich. Der Abfrageparameter file_id ist die ID der Datei, die heruntergeladen werden soll.

  • Optional. Der Abfrageparameter mime_type gibt den MIME-Typ an, der von der Methode verwendet werden soll. Sie ist nur beim Herunterladen von nicht-Blob-Medieninhalten verfügbar, z. B. Google Workspace-Dokumente. Eine vollständige Liste der unterstützten MIME-Typen finden Sie unter MIME-Typen für Google Workspace-Dokumente exportieren.

    Wenn der MIME-Typ nicht festgelegt ist, wird das Google Workspace-Dokument mit einem Standard-MIME-Typ heruntergeladen. Weitere Informationen finden Sie unter Standard-MIME-Typen.

  • Optional. Der Abfrageparameter revision_id ist die Versions-ID der herunterzuladenden Datei. Sie ist nur beim Herunterladen von Blob-Dateien, Google Docs- und Google Sheets-Dateien verfügbar. Gibt den Fehlercode INVALID_ARGUMENT zurück, wenn eine bestimmte Version von nicht unterstützten Dateien heruntergeladen wird.

Die download()-Methode ist die einzige Möglichkeit, Vids-Dateien im MP4-Format herunterzuladen. Sie eignet sich in der Regel am besten zum Herunterladen der meisten Videodateien.

Downloadlinks, die für Google Docs oder Google Tabellen generiert wurden, leiten zuerst zu einer Weiterleitung weiter. Klicken Sie auf den neuen Link, um die Datei herunterzuladen.

Sowohl die Anfrage an die download()-Methode, mit der der LRO gestartet wird, als auch die Anfrage zum Abrufen des endgültigen Download-URIs sollten Ressourcenschlüssel verwenden. Weitere Informationen finden Sie unter Über Ressourcenschlüssel auf per Link freigegebene Drive-Dateien zugreifen.

Das Anfrageprotokoll wird hier angezeigt.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Ersetzen Sie FILE_ID durch die fileId der Datei, die Sie herunterladen möchten.

Standard-MIME-Typen

Wenn beim Herunterladen von Inhalten, die keine Blobs sind, kein MIME-Typ festgelegt ist, werden die folgenden Standard-MIME-Typen zugewiesen:

Dokumenttyp Format MIME-Typ Dateiendung
Google Apps Script JSON application/vnd.google-apps.script+json .json
Google Docs Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document DOCX
Google Zeichnungen PNG image/png PNG
Google Formulare ZIP application/zip .zip
Google Sheets Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet XLSX
Google Sites Rohtext text/raw .txt
Google Präsentationen Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation PPTX
Google Vids MP4 application/mp4 .mp4
Jamboard PDF application/pdf PDF

Downloadantwort

Wenn Sie die Methode download() aufrufen, besteht der Antworttext aus einer Ressource, die einen lang andauernden Vorgang darstellt. Die Methode gibt in der Regel einen Link zum Herunterladen des Dateiinhalts zurück.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Diese Ausgabe enthält die folgenden Werte:

Das Feld partialDownloadAllowed gibt an, ob ein teilweiser Download zulässig ist. „Wahr“, wenn Blob-Dateiinhalte heruntergeladen werden.

Details zu einem lang andauernden Vorgang abrufen

Lang andauernde Vorgänge sind Methodenaufrufe, die viel Zeit in Anspruch nehmen können. Normalerweise werden neu erstellte Downloadvorgänge anfangs im Status „Ausstehend“ (done=null) zurückgegeben, insbesondere bei Vids-Dateien.

Sie können die Ressource operations der Drive API verwenden, um den Status des LRO für die Verarbeitung zu prüfen. Geben Sie dazu den eindeutigen, vom Server zugewiesenen Namen an.

Mit der Methode get() wird der aktuelle Status eines Vorgangs mit langer Ausführungszeit asynchron abgerufen. Clients können diese Methode nutzen, um die Ergebnisse eines Vorgangs nach gewissen Zeitabständen zu testen, wie vom API-Dienst empfohlen.

Lang andauernden Vorgang abfragen

Wenn Sie einen verfügbaren LRO abfragen möchten, rufen Sie die Methode get() wiederholt auf, bis der Vorgang abgeschlossen ist. Verwenden Sie einen exponentiellen Backoff zwischen den Abfrageanfragen, z. B. 10 Sekunden.

Ein LRO bleibt mindestens 12 Stunden lang verfügbar, in einigen Fällen auch länger. Diese Dauer kann sich ändern und je nach Dateityp variieren. Sobald die Ressource abgelaufen ist, ist eine neue download()-Methodenanfrage erforderlich.

Alle Anfragen an get() sollten Ressourcenschlüssel verwenden. Weitere Informationen finden Sie unter Über Ressourcenschlüssel auf per Link freigegebene Drive-Dateien zugreifen.

Die Anfrageprotokolle werden hier angezeigt.

Methodenaufruf

operations.get(name='NAME');

Ersetzen Sie NAME durch den vom Server zugewiesenen Namen des Vorgangs, wie er in der Antwort auf die download()-Methodenanfrage angezeigt wird.

curl

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Ersetzen Sie NAME durch den vom Server zugewiesenen Namen des Vorgangs, wie er in der Antwort auf die download()-Methodenanfrage angezeigt wird.

Der Befehl verwendet den Pfad /drive/v3/operations/NAME.

Hinweis: name wird nur in der Antwort auf eine download()-Anfrage zurückgegeben. Es gibt keine andere Möglichkeit, sie abzurufen, da die Drive API die Methode List() nicht unterstützt. Wenn der Wert von name verloren geht, musst du eine neue Antwort generieren, indem du die download()-Methodenanfrage noch einmal aufrufst.

Die Antwort auf eine get()-Anfrage besteht aus einer Ressource, die einen Vorgang mit langer Ausführungszeit darstellt. Weitere Informationen finden Sie unter Downloadantwort.

Wenn die Antwort den Status „Abgeschlossen“ (done=true) enthält, ist der langlaufende Vorgang beendet.

Überarbeitung herunterladen

Sie können den Wert des Felds headRevisionId aus der Ressource files verwenden, um die neueste Version herunterzuladen. Dadurch wird die Version abgerufen, die den Metadaten der zuvor abgerufenen Datei entspricht. Wenn Sie die Daten für alle vorherigen Versionen der Datei herunterladen möchten, die noch in der Cloud gespeichert sind, können Sie die Methode list() für die Ressource revisions mit dem Parameter fileId aufrufen. Dadurch werden alle revisionIds in der Datei zurückgegeben.

Wenn Sie den Inhalt der Revision von Blob-Dateien herunterladen möchten, müssen Sie die Methode get() für die revisions-Ressource mit der ID der herunterzuladenden Datei, der ID der Revision und dem URL-Parameter alt=media aufrufen. Der alt=media-URL-Parameter teilt dem Server mit, dass ein Inhaltsdownload als alternatives Antwortformat angefordert wird.

Versionen von Google Docs-, Sheets-, Präsentations- und Vids-Dateien können nicht mit der get()-Methode mit der alt=media-URL heruntergeladen werden . Andernfalls wird der Fehler fileNotDownloadable ausgegeben.

Der URL-Parameter alt=media ist ein Systemparameter, der in allen Google REST APIs verfügbar ist. Wenn Sie eine Clientbibliothek für die Drive API verwenden, müssen Sie diesen Parameter nicht explizit festlegen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Ersetzen Sie Folgendes:

  • FILE_ID: Die fileId der Datei, die Sie herunterladen möchten.
  • REVISION_ID: Die revisionId der Version, die Sie herunterladen möchten.

Bei Überarbeitungen in Google Docs, Google Zeichnungen und Google Präsentationen werden die Versionsnummern automatisch hochgezählt. Die Zahlenreihe kann jedoch Lücken aufweisen, wenn Versionen gelöscht werden. Sie sollten sich also nicht auf die fortlaufende Nummerierung verlassen, um Versionen abzurufen.

Fehlerbehebung bei LROs

Wenn ein LRO fehlschlägt, enthält die Antwort einen kanonischen Google Cloud-Fehlercode.

In der folgenden Tabelle wird die Ursache der einzelnen Codes erläutert und es wird empfohlen, wie Sie damit umgehen sollten. Bei vielen Fehlern wird empfohlen, die Anfrage mit exponentiellem Backoff noch einmal auszuführen.

Weitere Informationen zu diesem Fehlermodell und zur Arbeit damit finden Sie in der API-Designanleitung.

Code Enum Beschreibung Empfohlene Maßnahmen
1 CANCELLED Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer. Wiederholen Sie den Vorgang.
2 UNKNOWN Dieser Fehler wird möglicherweise zurückgegeben, wenn ein Status-Wert, der von einem anderen Adressbereich empfangen wurde, zu einem Fehlerbereich gehört, der in diesem Adressbereich nicht bekannt ist. Wenn der API-Fehler nicht genügend Informationen zurückgibt, wird er möglicherweise in diesen Fehler konvertiert. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
3 INVALID_ARGUMENT Der Client hat ein ungültiges Argument angegeben. Dieser Fehler unterscheidet sich von FAILED_PRECONDITION. INVALID_ARGUMENT gibt Argumente an, die ungeachtet des Systemstatus problematisch sind (z. B. ein ungültiger Dateiname). Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
4 DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Bei Vorgängen, die den Systemstatus verändern, kann dieser Fehler angezeigt werden, auch wenn der Vorgang erfolgreich abgeschlossen wurde. Zum Beispiel könnte eine erfolgreiche Antwort von einem Server so lange verzögert worden sein, dass die Frist abgelaufen ist. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
5 NOT_FOUND Eine angeforderte Entität, z. B. eine FHIR-Ressource, wurde nicht gefunden. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
6 ALREADY_EXISTS Die Entität, die ein Client erstellen wollte, z. B. eine DICOM-Instanz, ist bereits vorhanden. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
7 PERMISSION_DENIED Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs. Dieser Fehlercode impliziert nicht, dass die Anfrage gültig ist oder die angefragte Entität existiert oder andere Vorbedingungen erfüllt. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
8 RESOURCE_EXHAUSTED Eine Ressource ist aufgebraucht, z. B. ein pro Projekt festgelegtes Kontingent. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Möglicherweise wird das Kontingent im Laufe der Zeit verfügbar.
9 FAILED_PRECONDITION Der Vorgang wurde abgelehnt, weil der Systemzustand nicht für die Ausführung des Vorgangs geeignet ist. Beispiel: Das zu löschende Verzeichnis ist nicht leer oder ein rmdir-Vorgang wird auf ein Nicht-Verzeichnis angewendet. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
10 ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Parallelitätsproblems wie einer fehlgeschlagenen Sequencer-Überprüfung oder einer abgebrochenen Transaktion. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
11 OUT_OF_RANGE Beim Vorgang wurde versucht, den gültigen Bereich zu überschreiten, z. B. bei einer Such- oder Leseaktion hinter dem Dateiende. Im Gegensatz zu INVALID_ARGUMENT zeigt dieser Fehler ein Problem an, das behoben werden kann, wenn sich der Systemstatus ändert. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
12 UNIMPLEMENTED Dieser Vorgang ist nicht implementiert oder wird in der Drive API nicht unterstützt bzw. nicht aktiviert. Wiederholen Sie den Vorgang nicht.
13 INTERNAL Interne Fehler. Dies weist darauf hin, dass bei der Verarbeitung des zugrunde liegenden Systems ein unerwarteter Fehler aufgetreten ist. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
14 UNAVAILABLE Die Drive API ist nicht verfügbar. Dies ist höchstwahrscheinlich ein vorübergehender Zustand, der durch Wiederholen mit einem exponentiellen Backoff korrigiert werden kann. Es ist nicht immer sicher, nicht idempotente Vorgänge zu wiederholen. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
15 DATA_LOSS Dauerhafter Datenverlust oder Datenkorruption. Wenden Sie sich an Ihren Systemadministrator. Der Systemadministrator sollte sich an einen Supportmitarbeiter wenden, wenn Daten verloren gegangen sind oder beschädigt wurden.
16 UNAUTHENTICATED Die Anfrage enthält keine gültigen Authentifizierungsdaten für diesen Vorgang. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.