Best Practices für optimale Ergebnisse

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:

Wie sich ein Dokument zwischen Methodenaufrufen ändern kann.

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:

  1. Rufen Sie das Dokument mit der Methode documents.get ab und speichern Sie den revisionId aus der zurückgegebenen documents-Ressource.
  2. Schreiben Sie Ihre Aktualisierungsanfragen.
  3. Fügen Sie ein optionales WriteControl-Objekt mit einer der beiden Optionen ein:
    1. Das Feld requiredRevisionId ist auf den revisionId 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.
    2. Das Feld targetRevisionId ist auf den revisionId 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.

Ein Beispiel für das Erstellen einer Batchanfrage mit WriteControl finden Sie in diesem Beispiel für eine Batchanfrage.