Dokument

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:

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

In Abbildung 1 verläuft für einen Nutzer, der mit der Ressource documents interagiert, der folgende 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 atomar auszuführen und das Dokument mit Daten zu füllen.
  4. 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:

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

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

  1. Eine Anwendung 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. Der zurückgegebene JSON-Code enthält den Dokumentinhalt, die Formatierung und andere Funktionen.
  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 atomar auszuführen, um das Dokument zu aktualisieren.
  5. 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.