Diese Seite wurde von der Cloud Translation API übersetzt.

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 Aufrufthread nicht offen halten, während die Aufgabe ausgeführt wird, da dies die Nutzerfreundlichkeit beeinträchtigt. Stattdessen ist es besser, dem Nutzer eine Art Zusage zu geben und ihm zu erlauben, später noch einmal nachzusehen.

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

Die Methode gibt eine operations-Ressource an den Client zurück. Mit der Ressource operations können Sie den Status der API-Methode asynchron abrufen, indem Sie den Vorgang über die Methode get abfragen. LROs in der Drive API entsprechen dem Google Cloud-LRO-Designmuster.

Weitere Informationen finden Sie unter Vorgänge mit langer Laufzeit.

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“

files.download aufrufen: Wenn Ihre App die Methode download aufruft, wird die Downloadanfrage für die Datei über die Drive API gestartet. Weitere Informationen finden Sie unter Dateien herunterladen.
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 erteilt wurde, wird der Nutzer aufgefordert, sich anzumelden. Ihre App fragt auch nach Zugriff mit Bereichsangaben, die Sie beim Einrichten der Authentifizierung angeben.
Download starten: Es wird eine Drive API-Anfrage gesendet, um den Dateidownload zu starten. Die Anfrage kann an Google Vids oder andere Google Workspace-Inhalte gerichtet sein.
LRO starten: Ein Vorgang mit langer Ausführungszeit wird gestartet und verwaltet den Downloadprozess.
Ausstehenden Vorgang zurückgeben: Die Drive API gibt einen ausstehenden Vorgang zurück, der Informationen zum Nutzer enthält, der die Anfrage stellt, sowie mehrere Dateimetadatenfelder.
Erster ausstehender Status: Ihre App empfängt den ausstehenden Vorgang zusammen mit dem ersten ausstehenden Status done=null. Das bedeutet, dass die Datei noch nicht zum Download bereit ist und der Vorgangsstatus „Ausstehend“ lautet.
operations.get aufrufen und Ergebnis bestätigen: Ihre App ruft die get in den empfohlenen Intervallen auf, um das Ergebnis des Vorgangs abzufragen und den aktuellen Status eines Vorgangs mit langer Ausführungszeit abzurufen. Wenn der Status „Ausstehend“ (done=false) zurückgegeben wird, muss Ihre App so lange abfragen, bis der Vorgang den Status „Abgeschlossen“ (done=true) zurückgibt. Bei großen Dateien müssen Sie möglicherweise mehrmals abfragen. Weitere Informationen finden Sie unter Details zu einem Vorgang mit langer Ausführungszeit abrufen.
Ausstehenden Status prüfen: Wenn der ausstehende Status von done=true vom LRO zurückgegeben wird, bedeutet dies, dass die Datei zum Herunterladen bereit ist und der Vorgangsstatus abgeschlossen ist.
Abgeschlossenen Vorgang mit Download-URI zurückgeben: Sobald der Vorgang mit langer Ausführungszeit abgeschlossen ist, gibt die Drive API den Download-URI zurück und die Datei ist für den Nutzer verfügbar.

Dateien herunterladen

Wenn Sie Inhalte im Rahmen eines lang andauernden 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 herunterzuladenden Datei.
Optional. Der Abfrageparameter mime_type gibt den MIME-Typ an, der von der Methode verwendet werden soll. Sie ist nur beim Herunterladen von Media-Inhalten verfügbar, die keine Blobs sind, z. B. Google Workspace-Dokumente. Eine vollständige Liste der unterstützten MIME-Typen finden Sie unter MIME-Typen für den Export von Google Workspace-Dokumenten.

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 Revisions-ID der Datei, die heruntergeladen werden soll. Sie ist nur beim Herunterladen von Blob-Dateien, Google Docs und Google Sheets verfügbar. Gibt den Fehlercode INVALID_ARGUMENT zurück, wenn eine bestimmte Version nicht unterstützter Dateien heruntergeladen wird.

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

Für Google Docs oder Google Sheets generierte Downloadlinks geben anfangs eine Weiterleitung zurück. Klicken Sie auf den neuen Link, um die Datei herunterzuladen.

Für eine Anfrage an die download-Methode, mit der der LRO gestartet wird, und für die Anfrage zum Abrufen des endgültigen Download-URI sollten beide Ressourcen-Schlüssel verwendet werden. Weitere Informationen finden Sie unter Über Ressourcen-Schlüssel auf über Links 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	Rohdaten	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

Beim Aufrufen der Methode download besteht der Antworttext aus einer Ressource, die einen Vorgang mit langer Ausführungszeit 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:

RESOURCE_KEY: Ein Ressourcenschlüssel schützt Ihre Datei vor unbeabsichtigtem Zugriff. Weitere Informationen finden Sie unter Über einen Link freigegebene Drive-Dateien mit Ressourcenschlüsseln aufrufen.
NAME: Der vom Server zugewiesene Name.
DOWNLOAD_URI: Der endgültige Download-URI für die Datei.

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

Details zu einem Vorgang mit langer Ausführungszeit abrufen

Lange laufende Vorgänge sind Methodenaufrufe, die viel Zeit in Anspruch nehmen können. Neu erstellte Downloadvorgänge werden in der Regel zuerst im Status „Ausstehend“ (done=null) zurückgegeben, insbesondere bei Vids-Dateien.

Sie können die operations-Ressource verwenden, die von der Drive API bereitgestellt wird, um den Status des LRO für die Verarbeitung zu prüfen. Dazu müssen Sie den eindeutigen, vom Server zugewiesenen Namen angeben.

Die Methode get ruft den letzten Status eines lang andauernden Vorgangs asynchron ab. 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

Für die Abfrage eines verfügbaren LRO rufen Sie die Methode get wiederholt auf, bis der Vorgang abgeschlossen ist. Verwenden Sie einen exponentiellen Backoff zwischen den einzelnen Abfrageanfragen, z. B. 10 Sekunden.

Ein LRO ist 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 abläuft, ist eine neue download-Methodenanfrage erforderlich.

Für alle Anfragen an get müssen Ressourcenschlüssel verwendet werden. Weitere Informationen finden Sie unter Über Ressourcen-Schlüssel auf über Links freigegebene Drive-Dateien zugreifen.

Hier werden die Anfrageprotokolle 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.

Beachten Sie, dass name nur in der Antwort auf eine download-Anfrage zurückgegeben wird. 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, müssen Sie eine neue Antwort generieren, indem Sie die download-Methodenanfrage noch einmal aufrufen.

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

Wenn die Antwort den Status „Abgeschlossen“ (done=true) enthält, ist der Vorgang mit langer Ausführungszeit abgeschlossen.

Überarbeitung herunterladen

Sie können den Wert des Felds headRevisionId aus der Ressource files verwenden, um die letzte Überarbeitung herunterzuladen. Dadurch wird die Revision abgerufen, die den Metadaten der Datei entspricht, die Sie zuvor abgerufen haben. Wenn Sie die Daten für alle vorherigen Überarbeitungen 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 Revisionsinhalt von Blob-Dateien herunterladen möchten, müssen Sie die Methode get für die Ressource revisions mit der ID der herunterzuladenden Datei, der ID der Revision und dem URL-Parameter alt=media aufrufen. Der URL-Parameter alt=media teilt dem Server mit, dass ein Inhaltsdownload als alternatives Antwortformat angefordert wird.

Revisionen für Google Docs, Sheets, Präsentationen und Vids können nicht mit der get-Methode und der alt=media-URL heruntergeladen werden . Andernfalls wird ein fileNotDownloadable-Fehler generiert.

Der URL-Parameter alt=media ist ein Systemparameter, der für alle 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 Revision, die Sie herunterladen möchten.

Bei Überarbeitungen in Google Docs, Google Zeichnungen und Google Präsentationen werden die Revisionsnummern automatisch erhöht. Die Zahlenfolge kann jedoch Lücken aufweisen, wenn Überarbeitungen gelöscht werden. Sie sollten sich daher nicht auf fortlaufende Zahlen verlassen, um Überarbeitungen abzurufen.

Probleme mit LROs beheben

Schlägt ein LRO fehl, enthält seine Antwort einen kanonischen Google Cloud-Fehlercode.

In der folgenden Tabelle wird die Ursache der einzelnen Codes erläutert und eine Empfehlung für den Umgang mit dem Code gegeben. 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 erst, 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 erst, 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 erst, 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, die angeforderte Entität vorhanden ist oder andere Vorbedingungen erfüllt sind.	Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
8	`RESOURCE_EXHAUSTED`	Eine Ressource ist aufgebraucht, z. B. ein Kontingent pro Projekt.	Wiederholen Sie den Vorgang mit exponentiellem Backoff. Das Kontingent wird möglicherweise 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 erst, 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 erst, wenn das Problem behoben ist.
12	`UNIMPLEMENTED`	Dieser Vorgang ist nicht implementiert oder wird in der Drive API nicht unterstützt bzw. ist in der Drive API 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 exponentiellem 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 oder beschädigt wurden.
16	`UNAUTHENTICATED`	Die Anfrage enthält keine gültigen Authentifizierungsdaten für diesen Vorgang.	Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.

Dateien herunterladen und exportieren