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 für ein bestimmtes Dokument atomar auszufü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 stabil, auch wenn sich der Dokumentname ändert.
https://docs.google.com/document/d/DOCUMENT_ID/edit
Mit dem folgenden regulären Ausdruck kann die documentId
aus einer Google Docs-URL extrahiert werden:
/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 häufig ist es erforderlich, auch 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 Drive-Methode files.list
abrufen. Wenn die Methode ohne Parameter aufgerufen wird, wird für den Nutzer eine Liste aller Dateien und Ordner einschließlich der IDs zurückgegeben.
Der MIME-Typ eines Dokuments gibt Datentyp und 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 nur nach MIME-Typ nach Google Docs-Dateien in Google Drive suchen möchten, fügen Sie den folgenden Suchstringfilter an:
q: mimeType = 'application/vnd.google-apps.document'
Weitere Informationen zu Suchstringfiltern finden Sie unter Nach Dateien und Ordnern 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 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.
Die Methoden Get
und List
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 nach ID ab. Gibt eine Instanz der Ressource files zurück. |
Die 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:
In Abbildung 1 interagiert ein Nutzer mit der Ressource documents
. Dabei erfolgt der Informationsfluss so:
- Eine App ruft die Methode
documents.create
auf einem Webserver auf. - Der Webserver sendet eine HTTP-Antwort, die eine Instanz des erstellten Dokuments als
documents
-Ressource enthält. - 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. - Der Webserver sendet eine HTTP-Antwort. Einige
documents.batchUpdate
-Methoden stellen einen Antworttext mit Informationen zu den angewendeten Anfragen bereit, während andere eine leere Antwort ausgeben.
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 zeigt, wie das funktioniert:
In Abbildung 2 wird der Informationsfluss für einen Nutzer dargestellt, der mit der documents
-Ressource interagiert:
- Eine App ruft die Methode
documents.get
auf einem Webserver mit demdocumentId
der zu findenden Datei auf. - 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 Dokumentinhalt, die Formatierung und andere Funktionen. - Die Anwendung parst den JSON-Code, damit der Nutzer bestimmen kann, welcher Inhalt oder welches Format aktualisiert werden soll.
- Die App ruft die Methode
documents.batchUpdate
auf, um eine Reihe von Bearbeitungsanfragen atomar auszuführen und das Dokument zu aktualisieren. - Der Webserver sendet eine HTTP-Antwort. Einige
documents.batchUpdate
-Methoden stellen einen Antworttext mit Informationen zu den angewendeten Anfragen bereit, während andere eine leere Antwort ausgeben.
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.
Weitere Informationen
- Struktur eines Google Docs-Dokuments
- Anfragen und Antworten
- Regeln und Verhalten für strukturelle Änderungen
- Best Practices für optimale Ergebnisse