In diesem Leitfaden werden Konzepte vorgestellt. Dazu gehören die primären Methoden der Google Docs API, der Zugriff auf ein Dokument und der Workflow beim Erstellen eines Dokuments.
API-Methoden
Die Ressource documents
enthält 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 bestimmten Dokuments abzurufen. - Verwenden Sie die Methode
documents.batchUpdate
, um eine Reihe von Aktualisierungen atomar für ein bestimmtes Dokument auszuführen.
Die Methoden documents.get
und documents.batchUpdate
erfordern einen documentId
als Parameter, um das Zieldokument anzugeben. Die Methode documents.create
gibt eine Instanz des erstellten Dokuments zurück, aus der Sie das 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 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
der 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. Verwenden Sie beispielsweise zum Kopieren von Docs-Dateien 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 „Meine Ablage“ eines Nutzers abrufen möchten, ist es oft erforderlich, zuerst mit der files.list
-Methode von Drive die ID für eine Datei abzurufen. 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 in „Meine Ablage“ nur nach MIME-Typ nach Google Docs-Dateien 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 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 Byteinhalte von Google Workspace-Dokumenten 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.
Die Methoden Get
und List
vergleichen
In der folgenden Tabelle werden die Unterschiede zwischen den Methoden in Google Drive und Google Docs und die jeweils zurückgegebenen Daten beschrieben:
Operator | Beschreibung | Nutzung |
---|---|---|
drive.files.get |
Ruft die Metadaten einer Datei nach ID ab. Gibt eine Instanz der files -Ressource 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. | Rufen Sie eine Liste mit Nutzerdateien ab, wenn Sie nicht sicher sind, welche Datei geändert werden muss. |
docs.documents.get |
Ruft die neueste Version des angegebenen Dokuments ab, einschließlich aller Formatierungen und Text. Gibt eine Instanz der documents -Ressource zurück. |
Das Dokument für eine bestimmte Dokument-ID abrufen. |
Workflow für die Dokumenterstellung
Das Erstellen und Ausfüllen eines neuen Dokuments ist einfach, da es keinen vorhandenen Inhalt gibt, über den man sich Sorgen machen muss, und keine Mitbearbeiter, die den Dokumentstatus ändern können. Konzeptionell funktioniert dies so, wie im folgenden Sequenzdiagramm gezeigt:
In Abbildung 1 verläuft für einen Nutzer, der mit der Ressource documents
interagiert, der folgende 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 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 Aktualisierung von Dokumenten
Das Aktualisieren bestehender Dokumente ist komplexer. Bevor Sie aussagekräftige Aufrufe zum Aktualisieren eines Dokuments ausführen können, müssen Sie seinen aktuellen Status kennen: aus welchen Elementen es besteht, welcher Inhalt sich in diesen Elementen befindet und in welcher Reihenfolge die Elemente im Dokument sind. Das folgende Sequenzdiagramm zeigt, wie das funktioniert:
In Abbildung 2 sieht ein Nutzer, der mit der Ressource documents
interagiert, den folgenden Informationsfluss:
- Eine Anwendung ruft die Methode
documents.get
auf einem Webserver mit demdocumentId
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 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 Anwendung ruft die Methode
documents.batchUpdate
auf, um eine Reihe von Bearbeitungsanfragen atomar auszuführen, um 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 erfolgen. Weitere Informationen finden Sie im Abschnitt Für die Zusammenarbeit planen im Abschnitt mit den Best Practices.
Weitere Informationen
- Struktur eines Google Docs-Dokuments
- Anfragen und Antworten
- Regeln und Funktionsweise der Strukturbearbeitung
- Best Practices für optimale Ergebnisse