Dokument

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 documents Ressource 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 documents.create Methode, um ein Dokument zu erstellen.
  • Verwenden Sie die documents.get Methode, um den Inhalt eines bestimmten Dokuments abzurufen.
  • Verwenden Sie die documents.batchUpdate Methode, um eine Reihe von Aktualisierungen atomar für ein bestimmtes Dokument 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 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 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 die documentId der id 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, Methoden der Google Drive API zu verwenden, um mit den Docs-Dateien eines Nutzers zu interagieren. Wenn Sie beispielsweise Docs-Dateien kopieren möchten, verwenden Sie die Methode files.copy der Drive API. Weitere Informationen finden Sie unter Vorhandenes Dokument kopieren.

Standardmäßig wird ein neues Dokument bei Verwendung der Docs API 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 Docs-Dateien arbeiten

Wenn Sie ein Dokument aus „Meine Ablage“ eines Nutzers abrufen möchten, müssen Sie häufig zuerst die Methode von Drive files.list verwenden, um die ID für eine 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-Typformat für Docs ist application/vnd.google-apps.document. Eine Liste der MIME-Typen finden Sie unter Unterstützte MIME-Typen in Google Workspace und Google Drive Typen.

Wenn Sie nur nach Docs-Dateien in „Meine Ablage“ 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 die documentId kennen, können Sie mit der documents.get Methode eine vollständige Instanz des angegebenen Dokuments abrufen. Weitere Informationen finden Sie unter Anfragen und Antworten.

Wenn Sie Byte-Inhalte 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 MIME-Typ für den Export. Weitere Informationen finden Sie unter Inhalte von Google Workspace-Dokumenten exportieren.

Methoden Get und List vergleichen

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

Operator Beschreibung Nutzung
drive.files.get Ruft die Metadaten einer Datei anhand der ID ab. Gibt eine Instanz der files Ressource 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. Eine Liste der Nutzerdateien abrufen, 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 documents Ressource zurück. Das Dokument für eine bestimmte Dokument-ID abrufen.

Workflow zum Erstellen von Dokumenten

Das Erstellen und Füllen eines neuen Dokuments ist einfach, da es keine vorhandenen Inhalte gibt und keine Mitbearbeiter den Dokumentstatus ändern können. Konzeptionell funktioniert dies wie im folgenden Sequenzdiagramm dargestellt:

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

In Abbildung 1 hat ein Nutzer, der mit der documents Ressource interagiert, den folgenden Informationsfluss:

  1. Eine App ruft die documents.create Methode auf einem Webserver auf.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des erstellten Dokuments als Ressource documents enthält.
  3. Optional ruft die App die documents.batchUpdate Methode auf, um eine Reihe von Bearbeitungsanfragen atomar auszuführen, um das Dokument mit Daten zu füllen.
  4. Der Webserver sendet eine HTTP-Antwort. Einige Methoden documents.batchUpdate enthalten einen Antworttext mit Informationen zu den angewendeten Anfragen, während andere eine leere Antwort zurückgeben.

Workflow zum Aktualisieren von Dokumenten

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 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 dies:

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

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

  1. Eine App ruft die documents.get Methode auf einem Webserver auf und gibt die documentId der zu suchenden Datei an.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des angegebenen Dokuments als Ressource documents 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, welcher Inhalt oder welche Formatierung aktualisiert werden soll.
  4. Die App 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 Methoden documents.batchUpdate enthalten einen Antworttext mit Informationen zu den angewendeten Anfragen, während andere eine leere Antwort zurückgeben.

In diesem Diagramm werden keine Workflows berücksichtigt, bei denen andere Mitbearbeiter gleichzeitig Aktualisierungen am selben Dokument vornehmen. Weitere Informationen finden Sie im Abschnitt Best Practices für die Zusammenarbeit.