Best Practices für optimale Ergebnisse

Bei der Verwendung des Google Docs-API sollten Sie mehrere Prinzipien beachten. Dazu gehören:

  • Für mehr Effizienz rückwärts bearbeiten
  • Zusammenarbeit planen
  • Verwenden Sie das Feld WriteControl, um Statuskonsistenz zu gewährleisten.

In den folgenden Abschnitten werden diese Prinzipien erläutert.

Für mehr Effizienz rückwärts bearbeiten

Ordnen Sie Ihre Anfragen in einem einzigen Aufruf der Methode documents.batchUpdate in absteigender Reihenfolge des Indexstandorts. Dadurch entfällt die Notwendigkeit, die Indexänderungen aufgrund von Einfügungen und Löschungen zu berechnen.

Zusammenarbeit planen

Es ist davon auszugehen, dass sich der Dokumentstatus ändert. Zwischen zwei Methodenaufrufen können andere Mitbearbeiter das Dokument aktualisieren, wie im folgenden Diagramm dargestellt:

Gibt an, 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 UI bearbeiten, erledigt Google Docs dies auf transparente Weise. Als API-Client muss Ihre Anwendung dies jedoch verwalten. Selbst wenn Sie keine Zusammenarbeit am Dokument erwarten, ist es wichtig, eine defensive Programmierung zu gewährleisten und sicherzustellen, dass der Dokumentstatus konsistent bleibt. Eine Möglichkeit, wie Sie für Konsistenz sorgen, finden Sie im Abschnitt WriteControl.

Zustandskonsistenz mit WriteControl herstellen

Wenn Sie ein Dokument lesen und dann aktualisieren, können Sie mit dem Feld WriteControl in der Methode documents.batchUpdate steuern, wie konkurrierende Änderungen gehandhabt werden. WriteControl steuert die Ausführung von Schreibanfragen.

So verwenden Sie das Tool:

  1. Rufen Sie das Dokument mit der Methode documents.get ab und speichern Sie das revisionId-Objekt aus der zurückgegebenen documents-Ressource.
  2. Verfassen Sie Ihre Aktualisierungsanfragen.
  3. Fügen Sie ein optionales WriteControl-Objekt mit einer von zwei Optionen ein:
    1. Das Feld requiredRevisionId ist auf den revisionId des Dokuments gesetzt, 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 die revisionId des Dokuments gesetzt, 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 berücksichtigt sowohl die Änderungen der Schreibanfrage als auch die Änderungen des Mitbearbeiters in eine neue Version des Dokuments. Der Docs-Server ist für die Zusammenführung der Inhalte zuständig.

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