Dokument

In dieser Anleitung 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, mit denen Sie die Docs API aufrufen können. Mit den folgenden Methoden können Sie 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 angegebenen 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 der Sie die documentId lesen können. Weitere Informationen zu Docs API-Anfrage- und Antwortmethoden finden Sie unter Anfragen und Antworten.

Dokument-ID

documentId ist die eindeutige Kennung für das Dokument und kann aus der URL eines Dokuments abgeleitet werden. Es handelt sich um einen bestimmten 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 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 der id-Eigenschaft in der files-Ressource.

Dokumente in Google Drive verwalten

Docs-Dateien werden in Google Drive gespeichert, unserem cloudbasierten Speicherdienst. Die Docs API hat zwar eigene eigenständige Methoden, aber häufig ist es auch erforderlich, Google Drive API-Methoden zu verwenden, um mit den Docs-Dateien eines Nutzers zu interagieren. Wenn Sie beispielsweise Google-Dokumente 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 standardmäßig ein neues Dokument im Stammordner des Nutzers in Drive gespeichert. Es gibt Optionen zum Speichern einer Datei in einem Drive-Ordner. 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 häufig zuerst die Methode files.list von Drive verwenden, um die ID einer Datei abzurufen. Wenn Sie die Methode ohne Parameter aufrufen, wird eine Liste aller Dateien und Ordner des Nutzers zurückgegeben, einschließlich der IDs.

Der MIME-Typ eines Dokuments gibt den Datentyp und das Format an. Das MIME-Typ-Format 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 in „Meine Ablage“ nur nach Google-Dokumenten mit einem bestimmten MIME-Typ suchen möchten, hängen Sie den folgenden Filter für den Abfragestring an:

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

Weitere Informationen zu Filtern für Abfragestrings finden Sie unter Dateien und Ordner suchen.

Sobald 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 Methode files.export von Drive mit der documentId der zu exportierenden Datei und dem richtigen MIME-Typ für den Export. Weitere Informationen finden Sie unter Inhalte von Google Workspace-Dokumenten exportieren.

Get- und List-Methoden vergleichen

In der folgenden Tabelle werden die Unterschiede zwischen den Drive- und Docs-Methoden sowie die Daten beschrieben, die mit den einzelnen Methoden zurückgegeben werden:

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. Sie können eine Liste der Nutzerdateien abrufen, wenn Sie sich 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 des gesamten Texts. Gibt eine Instanz der Ressource documents zurück. Ruft das Dokument für eine bestimmte Dokument-ID ab.

Workflow zur Dokumenterstellung

Das Erstellen und Befüllen eines neuen Dokuments ist unkompliziert, 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 documents-Ressource. Dabei werden die folgenden Informationen ausgetauscht:

  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 geben einen Antworttext mit Informationen zu den angewendeten Anfragen zurück, während andere eine leere Antwort zurückgeben.

Workflow für Dokumentaktualisierung

Das Aktualisieren eines vorhandenen Dokuments ist komplexer. Bevor Sie sinnvolle Aufrufe zum Aktualisieren eines Dokuments ausführen können, müssen Sie den aktuellen Status des Dokuments kennen: aus welchen Elementen es besteht, welche Inhalte in diesen Elementen enthalten sind und in welcher Reihenfolge die Elemente im Dokument angeordnet sind. Das folgende Sequenzdiagramm veranschaulicht, wie das funktioniert:

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

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

  1. Eine App ruft die Methode documents.get auf einem Webserver mit dem documentId der zu suchenden Datei auf.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des angegebenen Dokuments als documents-Ressource enthält. Das zurückgegebene JSON enthält den Dokumentinhalt, die Formatierung und andere Funktionen.
  3. Die App parst das JSON, damit der Nutzer festlegen kann, welche Inhalte oder welches Format aktualisiert werden sollen.
  4. Die App 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 geben einen Antworttext mit Informationen zu den angewendeten Anfragen zurück, während andere eine leere Antwort zurückgeben.

In diesem Diagramm werden keine Workflows berücksichtigt, in denen andere Mitbearbeiter gleichzeitig Aktualisierungen am selben Dokument vornehmen. Weitere Informationen finden Sie im Abschnitt Zusammenarbeit planen.