Dokument

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

API-Methoden

Die Ressource documents bietet Methoden zum Aufrufen der Docs API. 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.
  • Mit der Methode documents.batchUpdate können Sie eine Reihe von Aktualisierungen für ein bestimmtes Dokument atomar ausfü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 dem Sie den documentId lesen können. Weitere Informationen zu Docs API-Anfragen und -Antwortmethoden finden Sie unter Anfragen und Antworten.

Dokument-ID

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

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

Mit dem folgenden regulären Ausdruck kann das documentId aus einer Google Docs-URL extrahiert werden:

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

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

Dokumente in Google Drive verwalten

Docs-Dateien werden in Google Drive, unserem cloudbasierten Speicherdienst, gespeichert. Die Docs API verfügt zwar über eigene eigenständige Methoden, aber häufig müssen auch Google Drive API-Methoden verwendet werden, um mit den Docs-Dateien eines Nutzers zu interagieren. Wenn Sie Docs-Dateien kopieren möchten, verwenden Sie beispielsweise 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 auf Google 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 „Meine Ablage“ eines Nutzers abrufen möchten, müssen Sie zuerst die files.list-Methode von Drive verwenden, um die ID einer Datei abzurufen. Bei einem Aufruf der Methode ohne Parameter 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. Das MIME-Typ-Format für 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 in „Meine Ablage“ nur nach Docs-Dateien nach MIME-Typ suchen möchten, hängen Sie den folgenden Abfragestringfilter an:

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

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

Sobald Sie den documentId kennen, rufen Sie mit der Methode documents.get eine vollständige Instanz des angegebenen Dokuments ab. Weitere Informationen finden Sie unter Anfragen und Antworten.

Wenn Sie Byteinhalte von Google Workspace-Dokumenten exportieren möchten, verwenden Sie die files.export-Methode von Drive mit der documentId der zu exportierenden Datei und dem richtigen Export-MIME-Typ. Weitere Informationen finden Sie unter Inhalte von Google Workspace-Dokumenten exportieren.

Die Methoden Get und List vergleichen

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

Operator Beschreibung Nutzung
drive.files.get Ruft die Metadaten einer Datei nach 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. Rufen Sie eine Liste der Nutzerdateien ab, wenn Sie nicht sicher sind, welche Datei Sie ändern müssen.
docs.documents.get Ruft die neueste Version des angegebenen Dokuments ab, einschließlich aller Formatierungen und Texte. Gibt eine Instanz der Ressource documents zurück. Rufen Sie das Dokument für eine bestimmte Dokument-ID ab.

Workflow für die Dokumenterstellung

Das Erstellen und Ausfüllen eines neuen Dokuments ist einfach, da keine Inhalte vorhanden sind und es keine Mitbearbeiter gibt, die den Dokumentstatus ändern können. Konzeptionell funktioniert dies wie im folgenden Sequenzdiagramm gezeigt:

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

In Abbildung 1 hat ein Nutzer, der mit der Ressource documents interagiert, den folgenden Informationsfluss:

  1. Eine Anwendung 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 Anwendung die Methode documents.batchUpdate auf, um eine Reihe von Bearbeitungsanfragen zum Füllen des Dokuments mit Daten atomar auszuführen.
  4. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden liefern einen Antworttext mit Informationen zu den angewendeten Anfragen, während andere eine leere Antwort anzeigen.

Workflow für Dokumentaktualisierung

Das Aktualisieren eines vorhandenen Dokuments ist komplexer. Bevor Sie aussagekräftige Aufrufe zum Aktualisieren eines Dokuments ausführen können, müssen Sie seinen aktuellen Zustand kennen: aus welchen Elementen es besteht, welcher Inhalt sich in diesen Elementen befindet und wie die Elemente innerhalb des Dokuments angeordnet sind. Das folgende Sequenzdiagramm zeigt, wie dies funktioniert:

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

In Abbildung 2 hat ein Nutzer, der mit der Ressource documents interagiert, den folgenden Informationsfluss:

  1. Eine Anwendung ruft die Methode documents.get auf einem Webserver mit der documentId der zu suchenden Datei auf.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des angegebenen Dokuments als documents-Ressource enthält. Der zurückgegebene JSON-Code enthält den Inhalt, die Formatierung und andere Funktionen des Dokuments.
  3. Die Anwendung parst den JSON-Code, damit der Nutzer bestimmen kann, welcher Inhalt oder welches Format aktualisiert werden soll.
  4. Die Anwendung ruft die Methode documents.batchUpdate auf, um eine Reihe von Bearbeitungsanfragen zum Aktualisieren des Dokuments atomar auszuführen.
  5. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden liefern einen Antworttext mit Informationen zu den angewendeten Anfragen, während andere eine leere Antwort anzeigen.

Dieses Diagramm berücksichtigt keine Workflows, bei denen gleichzeitige Aktualisierungen von anderen Mitbearbeitern im selben Dokument vorgenommen werden. Weitere Informationen finden Sie im Abschnitt zu Best Practices unter Zusammenarbeit planen.