Vorgänge mit langer Ausführungszeit verwalten

Ein Vorgang mit langer Ausführungszeit (Long-Running Operation, LRO) ist eine API-Methode, die länger dauert als für eine API-Antwort angemessen ist. Normalerweise sollten Sie den Aufruf-Thread nicht offen halten, während die Aufgabe ausgeführt wird, da dies die Nutzerfreundlichkeit beeinträchtigt. Stattdessen ist es besser, ein Promise an den Nutzer zurückzugeben und ihm zu ermöglichen, es später noch einmal zu überprüfen.

Die Google Drive API gibt bei jedem Aufruf der Methode download() für die Ressource files einen LRO zurück, 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. Fragen Sie dazu den Vorgang mit der Methode get() ab. 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.

1. files.download aufrufen: Wenn Ihre App die Methode download() aufruft, wird die Downloadanfrage der Drive API 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 in Ihrer Anwendung die Drive API mit einer Nutzerauthentifizierung aufgerufen werden muss, die noch nicht gewährt wurde, wird der Nutzer zur Anmeldung aufgefordert. 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 Vorgang noch 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 mit mehreren Abfragen zu rechnen. 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 mime_type-Abfrageparameter gibt den MIME-Typ an, der in 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 Überarbeitungs-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.

Bei Download-Links, die für Google Docs oder Google Tabellen generiert wurden, wird zunächst eine Weiterleitung zurückgegeben. 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:

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 Ressourcenschlüssel auf per Link freigegebene Drive-Dateien zugreifen.

• 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. „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.

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

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 abläuft, 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.

operations.get(name='NAME');

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

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, 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 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 neueste Version herunterzuladen. Dadurch wird die Version abgerufen, die den Metadaten der zuvor abgerufenen Datei entspricht. Wenn Sie die Daten aller 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 generiert.

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: Der 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 haben, wenn Überarbeitungen gelöscht werden. Daher sollten Sie sich zum Abrufen von Überarbeitungen nicht auf fortlaufende Nummern verlassen.

Fehlerbehebung bei LROs

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

In der folgenden Tabelle werden die Ursachen für jeden Code und eine Empfehlung zum Umgang mit dem Code erläutert. Bei vielen Fehlern empfiehlt es sich, die Anfrage noch einmal mit dem exponentiellen Backoff zu senden.

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

Weitere Informationen

• Dateien herunterladen und exportieren
• Dateiüberarbeitungen verwalten