Bei der Verwendung der Google Docs API sollten Sie verschiedene Prinzipien beachten. Dazu gehören:
- Für mehr Effizienz rückwärts bearbeiten
- Zusammenarbeit planen
- Sorgen Sie mit dem Feld
WriteControl
für Konsistenz des Zustands.
In den folgenden Abschnitten werden diese Prinzipien erläutert.
Für mehr Effizienz rückwärts bearbeiten
Sortieren Sie die Anfragen innerhalb eines einzigen Aufrufs der Methode documents.batchUpdate
in absteigender Reihenfolge des Indexstandorts. Dadurch müssen die Indexänderungen aufgrund von Einfügungen und Löschungen nicht berechnet werden.
Zusammenarbeit planen
Der Dokumentstatus wird sich voraussichtlich ändern. Zwischen einem Methodenaufruf und einem anderen können andere Mitbearbeiter das Dokument aktualisieren, wie im folgenden Diagramm dargestellt:
Dies kann zu Fehlern führen, wenn Ihre Indexe falsch sind. Wenn mehrere Nutzer ein Dokument über die Benutzeroberfläche bearbeiten, sorgt Google Docs dafür. Als API-Client muss Ihre Anwendung dies jedoch verwalten. Selbst wenn Sie keine Zusammenarbeit am Dokument erwarten, ist es wichtig, dass Sie defensiv programmieren und dafür sorgen, dass der Dokumentstatus konsistent bleibt. Eine Möglichkeit, Konsistenz zu gewährleisten, finden Sie im Abschnitt WriteControl
.
Zustandskonsistenz mit WriteControl herstellen
Wenn Sie ein Dokument lesen und anschließend aktualisieren, können Sie mit dem Feld WriteControl
in der Methode documents.batchUpdate
steuern, wie konkurrierende Änderungen verarbeitet werden. WriteControl
legt die Befugnis dafür fest, wie Schreibanfragen ausgeführt werden.
So verwenden Sie es:
- Rufen Sie das Dokument mit der Methode
documents.get
ab und speichern Sie denrevisionId
aus der zurückgegebenendocuments
-Ressource. - Schreiben Sie Ihre Aktualisierungsanfragen.
- Fügen Sie ein optionales
WriteControl
-Objekt mit einer der beiden Optionen ein:- Das Feld
requiredRevisionId
ist auf denrevisionId
des Dokuments festgelegt, auf das die Schreibanfrage angewendet wird. Wenn das Dokument seit der API-Leseanfrage geändert wurde, wird die Schreibanfrage nicht verarbeitet und es wird ein Fehler zurückgegeben. - Das Feld
targetRevisionId
ist auf denrevisionId
des Dokuments festgelegt, auf das die Schreibanfrage angewendet wird. Wenn das Dokument seit der API-Leseanfrage geändert wurde, werden die Änderungen der Schreibanfrage auf die Änderungen der Mitbearbeiter angewendet. Das Ergebnis der Schreibanfrage beinhaltet sowohl die Änderungen der Schreibanfrage als auch die Änderungen der Mitbearbeiter in einer neuen Überarbeitung des Dokuments. Der Docs-Server ist für die Zusammenführung der Inhalte verantwortlich.
- Das Feld
Ein Beispiel für das Erstellen einer Batchanfrage mit WriteControl
finden Sie in diesem Beispiel für eine Batchanfrage.