Einführung

Mit der Google Docs API können Sie Dokumente erstellen und ändern.

Anwendungen können in die Docs API eingebunden werden, um aus Nutzer- und Systemdaten ausgefeilte Dokumente zu erstellen. Die API ermöglicht Ihnen Folgendes:

  • Prozesse automatisieren
  • Dokumentation im Bulk erstellen
  • Rechnungen oder Verträge erstellen

Übersicht über die API

Die Ressource documents bietet Methoden zum Aufrufen der Docs API.

API-Methoden

Mit den folgenden Methoden können Sie Google Docs-Dokumente erstellen, lesen und aktualisieren:

  • Erstellen Sie mit documents.create ein Dokument.
  • Verwenden Sie documents.get, um den Inhalt eines bestimmten Dokuments abzurufen.
  • Verwenden Sie documents.batchUpdate, um eine Reihe von Aktualisierungen für ein bestimmtes Dokument atomar auszuführen.

Die Methoden get und batchUpdate erfordern einen documentId (siehe unten) als Parameter, um das Zieldokument anzugeben. Die Methode create gibt eine Instanz des erstellten Dokuments zurück, aus dem Sie die ID lesen können.

Batch-Updates

Die Methode batchUpdate nimmt eine Liste von Anfrageobjekten und führt Aktualisierungen in derselben Reihenfolge durch, in der sie in der Batchanfrage aufgeführt sind. Die Aktualisierungen im Batch-Update werden in kleinstmöglichen Schritten angewendet. Wenn also eine beliebige Anfrage ungültig ist, ist die gesamte Aktualisierung fehlgeschlagen und keine der (potenziell abhängigen) Änderungen wird angewendet.

Die Methode batchUpdate gibt eine Liste von Antwortobjekten zurück. Die Objekte in dieser Liste haben dieselbe Indexreihenfolge wie die entsprechende Anfrage.

In den Best Practices für Batchanfragen erfahren Sie, wie Sie API-Aufrufe in Batches zusammenfassen können. Informationen zu den Anfrage- und Antworttypen finden Sie in der Referenzdokumentation zu batchUpdate.

Dokument-ID

Dokument-IDs verweisen auf ein Dokument und können aus der URL abgeleitet werden:

https://docs.google.com/document/d/documentId/edit

documentId ist ein eindeutiger String, der Buchstaben, Ziffern und einige Sonderzeichen enthält. Mit dem folgenden regulären Ausdruck können Sie die Dokument-ID aus einer Google Docs-URL extrahieren:

/document/d/([a-zA-Z0-9-_]+)

Wenn Sie mit der Google Drive API vertraut sind, entspricht documentId der ID der Ressource File.

Positionen in einem Dokument: Indexe

Wenn Sie den Inhalt eines Dokuments aktualisieren, wird jede Aktualisierung an einer Stelle oder in einem Bereich innerhalb des Dokuments durchgeführt. Diese Positionen und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb eines enthaltenen Segments des Dokuments darstellen. Weitere Informationen zu Indexen und deren Verwendung finden Sie im Konzeptleitfaden Struktur eines Google Docs-Dokuments.

Workflow für die Dokumentaktualisierung

Das Erstellen und Ausfüllen eines neuen Dokuments ist einfach, da es keinen vorhandenen Inhalt gibt, über den man sich Gedanken machen muss, und es keine Mitbearbeiter gibt, die den Dokumentstatus ändern können. Konzeptionell funktioniert dies wie im folgenden Sequenzdiagramm gezeigt:

Workflow zum Erstellen und Ausfüllen eines neuen Dokuments.

Das Aktualisieren eines vorhandenen Dokuments ist komplexer. Bevor Sie aussagekräftige Aufrufe zum Aktualisieren eines Dokuments ausführen können, müssen Sie den aktuellen Status des Dokuments kennen: aus welchen Elementen besteht es, aus welchem Inhalt diese Elemente bestehen und wo sich diese Elemente im Dokument befinden. Das folgende Sequenzdiagramm zeigt, wie dies funktioniert:

Workflow zum Aktualisieren eines Dokuments.

Dieses Diagramm berücksichtigt keine Workflows, bei denen gleichzeitige Aktualisierungen durch andere Mitbearbeiter im selben Dokument vorgenommen werden. Weitere Informationen zu diesem Thema finden Sie unter Zusammenarbeit planen.