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:
In Abbildung 1 hat ein Nutzer, der mit der Ressource documents
interagiert, den folgenden Informationsfluss:
- Eine Anwendung 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 Anwendung die Methode
documents.batchUpdate
auf, um eine Reihe von Bearbeitungsanfragen zum Füllen des Dokuments mit Daten atomar auszuführen. - 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:
In Abbildung 2 hat ein Nutzer, der mit der Ressource documents
interagiert, den folgenden Informationsfluss:
- Eine Anwendung ruft die Methode
documents.get
auf einem Webserver mit derdocumentId
der zu suchenden 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 Inhalt, die Formatierung und andere Funktionen des Dokuments. - Die Anwendung parst den JSON-Code, damit der Nutzer bestimmen kann, welcher Inhalt oder welches Format aktualisiert werden soll.
- Die Anwendung ruft die Methode
documents.batchUpdate
auf, um eine Reihe von Bearbeitungsanfragen zum Aktualisieren des Dokuments atomar auszuführen. - 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.
Weitere Informationen
- Struktur eines Google Docs-Dokuments
- Anfragen und Antworten
- Strukturelle Bearbeitungsregeln und -verhalten
- Best Practices für optimale Ergebnisse