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. In der Regel möchten Sie den aufrufenden Thread nicht offen halten, während die Aufgabe ausgeführt wird, da dies die Nutzerfreundlichkeit beeinträchtigt. Stattdessen ist es besser, dem Nutzer eine Art Versprechen zurückzugeben und ihm zu ermöglichen, später noch einmal nachzusehen.

Die Google Drive API gibt jedes Mal einen LRO zurück, wenn Sie die download Methode für die files Ressource aufrufen, um den Inhalt einer Datei entweder über die Drive API oder ihre Client Bibliotheken 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 folgen dem Designmuster für LROs in Google Cloud pattern.

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

Prozessübersicht

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

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

2. Berechtigungen anfordern: Die Anfrage sendet Authentifizierungsdaten an die Drive API. Wenn Ihre App die Drive API mit der Authentifizierung eines Nutzers aufrufen muss, die noch nicht gewährt wurde, wird der Nutzer aufgefordert, sich anzumelden. Ihre App fordert auch Zugriff mit Bereichen an, die Sie bei der Einrichtung der Authentifizierung angeben.

3. Download starten: Es wird eine Drive API-Anfrage gesendet, um den Download der Datei zu starten. Die Anfrage kann an Google Vids oder andere Google Workspace-Inhalte gesendet werden.

4. LRO starten: Ein Vorgang mit langer Ausführungszeit wird gestartet und verwaltet den Download prozess.

5. 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 Metadatenfelder für die Datei.

6. Ausstehender Anfangsstatus: Ihre App empfängt den ausstehenden Vorgang zusammen mit dem ausstehenden Anfangsstatus done=null. Das bedeutet, dass die Datei noch nicht zum Download bereit ist und der Vorgangsstatus ausstehend ist.

7. Aufrufen von operations.get und Überprüfen des Ergebnisses: Ihre App ruft die Methode get in den empfohlenen Intervallen auf, um das Vorgangsergebnis abzufragen und den aktuellen Status eines Vorgangs mit langer Ausführungszeit abzurufen. Wenn der ausstehende Status done=false zurückgegeben wird, muss Ihre App die Abfrage fortsetzen, bis der Vorgang den Status „Abgeschlossen“ (done=true) zurückgibt. Bei großen Dateien müssen Sie die Abfrage möglicherweise mehrmals durchführen. Weitere Informationen finden Sie unter Details zu einem Vorgang mit langer Ausführungszeit abrufen.

8. Ausstehenden Status prüfen: Wenn der ausstehende Status done=true vom LRO zurückgegeben wird, bedeutet das, dass die Datei zum Download bereit ist und der Vorgangsstatus „Abgeschlossen“ ist.

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

Verwenden Sie die download Methode für die files Ressource, um Inhalte im Rahmen eines Vorgangs mit langer Ausführungszeit herunterzuladen. Die Methode verwendet die Parameter file_id, mime_type und revision_id:

• Erforderlich. Der Pfadparameter 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. Er ist nur verfügbar, wenn Sie keine Blob-Mediendateien (z. B. Google Workspace-Dokumente) herunterladen. 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 Überarbeitungs-ID der herunterzuladenden Datei. Er ist nur verfügbar, wenn Sie Blob-Dateien, Google Docs-Dateien und Google Sheets-Dateien herunterladen. Gibt den Fehlercode INVALID_ARGUMENT zurück, wenn eine bestimmte Überarbeitung für nicht unterstützte Dateien heruntergeladen wird.

Die Methode download ist die einzige Möglichkeit, Vids-Dateien im MP4-Format herunterzuladen, und eignet sich in der Regel am besten für den Download der meisten Videodateien. Wenn Sie versuchen, Google Vids-Dateien zu exportieren, wird der fileNotExportable Fehler zurückgegeben.

Downloadlinks, die für Google Docs- oder Google Sheets-Dateien generiert wurden, geben zunächst eine Weiterleitung zurück. Klicken Sie auf den neuen Link, um die Datei herunterzuladen.

Für eine Anfrage an die Methode download, die den LRO startet, und für die Anfrage zum Abrufen des endgültigen Download-URI sollten Ressourcenschlüssel verwendet werden. Weitere Informationen finden Sie unter Zugriff auf über Links freigegebene Drive-Dateien mit Ressourcenschlüsseln.

Hier wird das Anfrageprotokoll 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 download Methode 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 Zugriff auf über Links freigegebene Drive-Dateien mit Ressourcenschlüsseln.

• 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. Es ist true wenn BLOB-Dateiinhalte heruntergeladen werden.

Details zu einem Vorgang mit langer Ausführungszeit abrufen

Vorgänge mit langer Ausführungszeit sind Methodenaufrufe, die viel Zeit in Anspruch nehmen können. In der Regel werden neu erstellte Downloadvorgänge zunächst 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 zu prüfen. Dazu müssen Sie den eindeutigen vom Server zugewiesenen Namen angeben.

Die get Methode ruft den aktuellen Status eines Vorgangs mit langer Ausführungszeit asynchron ab. Clients können diese Methode nutzen, um die Ergebnisse eines Vorgangs nach gewissen Zeitabständen zu testen, wie vom API-Dienst empfohlen.

Vorgang mit langer Ausführungszeit abfragen

Für die Abfrage eines verfügbaren LRO rufen Sie die get Methode wiederholt auf, bis der Vorgang abgeschlossen ist. Verwenden Sie einen exponentiellen Backoff zwischen den 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 Anfrage für die Methode download erforderlich.

Für alle Anfragen an get sollten Ressourcenschlüssel verwendet werden. Weitere Informationen finden Sie unter Zugriff auf über Links freigegebene Drive-Dateien mit Ressourcenschlüsseln.

Hier werden die Anfrageprotokolle 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 der name nur in der Antwort auf eine download-Anfrage zurückgegeben wird. Es gibt keine andere Möglichkeit, ihn abzurufen, da die Drive API die Methode list nicht unterstützt. Wenn der Wert name verloren geht, müssen Sie eine neue Antwort generieren, indem Sie die Anfrage für die Methode download 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 Download antwort.

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

Überarbeitung herunterladen

Sie können den Wert des headRevisionId Felds aus der files Ressource verwenden, um die neueste Überarbeitung herunterzuladen. Dadurch wird die Überarbeitung abgerufen, die den Metadaten der zuvor abgerufenen Datei entspricht. 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 list Methode für die revisions Ressource mit dem fileId Parameter aufrufen. Dadurch werden alle revisionIds in der Datei zurückgegeben.

Wenn Sie den Überarbeitungsinhalt von BLOB-Dateien herunterladen möchten, müssen Sie die get Methode für die revisions Ressource mit der ID der herunterzuladenden Datei, der ID der Überarbeitung und dem alt System parameter aufrufen. Der Parameter alt=media teilt dem Server mit, dass ein Download von Inhalten als alternatives Antwortformat angefordert wird.

Der Systemparameter alt ist für alle Google REST APIs verfügbar. Wenn Sie eine Clientbibliothek für die Drive API verwenden, müssen Sie diesen Parameter nicht explizit festlegen.

Überarbeitungen für Google Docs-Dateien, Google Sheets-Dateien, Google Präsentationen-Dateien und Google Vids-Dateien können nicht mit der Methode get und dem Parameter alt=media heruntergeladen werden. Andernfalls wird der Fehler fileNotDownloadable zurückgegeben.

Hier wird das Anfrageprotokoll 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 Überarbeitung, die Sie herunterladen möchten.

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

Fehlerbehebung bei LROs

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

In der folgenden Tabelle sind die einzelnen Fehlercodes, der zugeordnete HTTP-Statuscode, eine Beschreibung und eine Empfehlung für den Umgang mit dem Fehlercode aufgeführt. Bei vielen Fehlern wird als empfohlene Maßnahme 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.

Weitere Informationen

• Dateien herunterladen und exportieren