Dokument

In diesem Leitfaden werden Konzepte wie die Hauptmethoden der Google Docs API, der Zugriff auf ein Dokument und der Workflow beim Erstellen eines Dokuments vorgestellt.

API-Methoden

Die Ressource documents bietet Methoden, mit denen Sie die Docs API aufrufen können. Mit den folgenden Methoden können Sie Google Docs-Dokumente erstellen, lesen und aktualisieren:

  • Verwenden Sie die Methode documents.create, um ein Dokument zu erstellen.
  • Verwenden Sie die Methode documents.get, um den Inhalt eines bestimmten Dokuments abzurufen.
  • Verwenden Sie die Methode documents.batchUpdate, um eine Reihe von Aktualisierungen an einem bestimmten Dokument in kleinstmöglichen Schritten durchzuführen.

Für die Methoden documents.get und documents.batchUpdate ist ein documentId als Parameter erforderlich, um das Zieldokument anzugeben. Die Methode documents.create gibt eine Instanz des erstellten Dokuments zurück, aus der Sie die documentId lesen können. Weitere Informationen zu Anfragen und Antwortmethoden der Docs API finden Sie unter Anfragen und Antworten.

Dokument-ID

Die documentId ist die eindeutige Kennung für das Dokument und kann aus der URL des Dokuments abgeleitet werden. Es ist ein bestimmter String, der Buchstaben, Zahlen und einige Sonderzeichen enthält. Dokument-IDs bleiben gleich, auch wenn sich der Dokumentname ändert.

https://docs.google.com/document/d/DOCUMENT_ID/edit

Mit dem folgenden regulären Ausdruck lässt sich die documentId aus einer Google Docs-URL extrahieren:

/document/d/([a-zA-Z0-9-_]+)

Wenn Sie mit der Google Drive API vertraut sind, entspricht documentId id in der Ressource files.

Dokumente in Google Drive verwalten

Docs-Dateien werden in Google Drive, unserem cloudbasierten Speicherdienst, gespeichert. Die Docs API hat zwar eigene eigenständige Methoden, aber oft ist es auch erforderlich, Google Drive API-Methoden zu verwenden, um mit den Docs-Dateien eines Nutzers zu interagieren. Wenn Sie beispielsweise Google Docs-Dateien kopieren möchten, verwenden Sie die Methode files.copy der Drive API. Weitere Informationen finden Sie unter Vorhandenes Dokument kopieren.

Wenn Sie die Docs API verwenden, wird ein neues Dokument standardmäßig im Stammordner des Nutzers in Drive gespeichert. Es gibt verschiedene Möglichkeiten, eine Datei in einem Drive-Ordner zu speichern. Weitere Informationen finden Sie unter Mit Google Drive-Ordnern arbeiten.

Mit Google Docs-Dateien arbeiten

Wenn Sie ein Dokument aus der „Meine Ablage“ eines Nutzers abrufen möchten, müssen Sie oft zuerst die ID der Datei mit der Google Drive-Methode files.list abrufen. Wenn Sie die Methode ohne Parameter aufrufen, wird eine Liste aller Dateien und Ordner einschließlich der IDs für den Nutzer zurückgegeben.

Der MIME-Typ eines Dokuments gibt den Datentyp und das Format an. Der MIME-Typ für Google Docs ist application/vnd.google-apps.document. Eine Liste der MIME-Typen finden Sie unter Von Google Workspace und Google Drive unterstützte MIME-Typen.

Wenn Sie nur nach Docs-Dateien in Google Drive suchen möchten, fügen Sie den folgenden Suchstringfilter hinzu:

q: mimeType = 'application/vnd.google-apps.document'

Weitere Informationen zu Suchstringfiltern finden Sie unter Nach Dateien und Ordnern suchen.

Wenn Sie die documentId kennen, verwenden Sie die Methode documents.get, um eine vollständige Instanz des angegebenen Dokuments abzurufen. Weitere Informationen finden Sie unter Anfragen und Antworten.

Wenn Sie den Byte-Inhalt eines Google Workspace-Dokuments exportieren möchten, verwenden Sie die Drive-Methode files.export mit der documentId der zu exportierenden Datei und dem richtigen MIME-Exporttyp. Weitere Informationen finden Sie unter Google Workspace-Dokumente exportieren.

Get- und List-Methode vergleichen

In der folgenden Tabelle werden die Unterschiede zwischen den Methoden für Google Drive und Google Docs sowie die jeweils zurückgegebenen Daten beschrieben:

Operator Beschreibung Nutzung
drive.files.get Ruft die Metadaten einer Datei anhand der ID ab. Gibt eine Instanz der Ressource files zurück. Metadaten für eine bestimmte Datei abrufen
drive.files.list Ruft die Dateien eines Nutzers ab. Gibt eine Liste von Dateien zurück. Wenn Sie nicht sicher sind, welche Datei Sie ändern müssen, können Sie eine Liste der Nutzerdateien abrufen.
docs.documents.get Ruft die neueste Version des angegebenen Dokuments ab, einschließlich aller Formatierungen und des gesamten Texts. Gibt eine Instanz der Ressource documents zurück. Ruft das Dokument für eine bestimmte Dokument-ID ab.

Workflow für die Dokumenterstellung

Das Erstellen und Befüllen eines neuen Dokuments ist ganz einfach, da es keine vorhandenen Inhalte gibt, um die Sie sich kümmern müssen, und keine Mitbearbeiter, die den Dokumentstatus ändern können. Konzeptionell funktioniert das wie im folgenden Sequenzdiagramm dargestellt:

Workflow zum Erstellen und Befüllen eines neuen Dokuments.
Abbildung 1: Workflow zum Erstellen und Befüllen eines neuen Dokuments.

In Abbildung 1 interagiert ein Nutzer mit der Ressource documents. Dabei erfolgt der Informationsfluss so:

  1. Eine App ruft die Methode documents.create auf einem Webserver auf.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des erstellten Dokuments als documents-Ressource enthält.
  3. Optional ruft die App die Methode documents.batchUpdate auf, um eine Reihe von Bearbeitungsanfragen atomar auszuführen und das Dokument mit Daten zu füllen.
  4. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden enthalten einen Antworttext mit Informationen zu den angewandten Anfragen, während andere eine leere Antwort zurückgeben.

Workflow für die Dokumentaktualisierung

Das Aktualisieren eines vorhandenen Dokuments ist etwas aufwendiger. Bevor Sie sinnvolle Aufrufe zum Aktualisieren eines Dokuments ausführen können, müssen Sie seinen aktuellen Status kennen: aus welchen Elementen es besteht, welche Inhalte sich in diesen Elementen befinden und welche Reihenfolge die Elemente im Dokument haben. Das folgende Sequenzdiagramm veranschaulicht, wie das funktioniert:

Workflow zum Aktualisieren eines Dokuments.
Abbildung 2: Workflow zum Aktualisieren eines Dokuments.

In Abbildung 2 wird der Informationsfluss für einen Nutzer dargestellt, der mit der documents-Ressource interagiert:

  1. Eine App ruft die Methode documents.get auf einem Webserver mit dem documentId der zu findenden Datei auf.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des angegebenen Dokuments als documents-Ressource enthält. Die zurückgegebene JSON-Datei enthält den Dokumentinhalt, die Formatierung und andere Funktionen.
  3. Die App analysiert die JSON-Datei, damit der Nutzer festlegen kann, welcher Inhalt oder welches Format aktualisiert werden soll.
  4. Die App ruft die Methode documents.batchUpdate auf, um eine Reihe von Bearbeitungsanfragen atomar auszuführen und das Dokument zu aktualisieren.
  5. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden enthalten einen Antworttext mit Informationen zu den angewandten Anfragen, während andere eine leere Antwort zurückgeben.

In diesem Diagramm werden keine Workflows berücksichtigt, bei denen gleichzeitige Aktualisierungen durch andere Mitbearbeiter im selben Dokument vorgenommen werden. Weitere Informationen finden Sie im Abschnitt zu Best Practices unter Für die Zusammenarbeit planen.