Best Practices für optimale Ergebnisse

Bei der Verwendung der Google Docs API sollten Sie einige Grundsätze beachten. Dazu gehören:

  • Rückwärts bearbeiten, um effizienter zu sein
  • Zusammenarbeit planen
  • Mit dem Feld WriteControl für Konsistenz sorgen
  • Tabs berücksichtigen

In den folgenden Abschnitten werden diese Grundsätze erläutert.

Rückwärts bearbeiten, um effizienter zu sein

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

Zusammenarbeit planen

Der Dokumentstatus ändert sich. Zwischen zwei Methodenaufrufen können andere Mitbearbeiter das Dokument aktualisieren, wie im folgenden Diagramm dargestellt:

So kann sich ein Dokument zwischen Methodenaufrufen ändern.

Das kann zu Fehlern führen, wenn Ihre Indexe falsch sind. Wenn mehrere Nutzer ein Dokument über die Benutzeroberfläche bearbeiten, wird dies in Google Docs transparent gehandhabt. Als API-Client muss Ihre App dies jedoch verwalten. Auch wenn Sie nicht davon ausgehen, dass andere Nutzer an dem Dokument mitarbeiten, ist es wichtig, defensiv zu programmieren und dafür zu sorgen, dass der Dokumentstatus konsistent bleibt. Eine Möglichkeit, für Konsistenz zu sorgen, finden Sie im Abschnitt WriteControl.

Statuskonsistenz mit WriteControl herstellen

Wenn Sie ein Dokument lesen und dann aktualisieren, können Sie das Verhalten bei konkurrierenden Änderungen mit dem Feld WriteControl in der Methode documents.batchUpdate steuern. WriteControl bietet die Möglichkeit, die Ausführung von Schreibanfragen zu steuern.

So verwenden Sie die Funktion:

  1. Rufen Sie das Dokument mit der Methode documents.get ab und speichern Sie die revisionId aus der zurückgegebenen documents-Ressource.
  2. Aktualisierungsanfragen verfassen
  3. Fügen Sie ein optionales WriteControl-Objekt mit einer von zwei Optionen ein:
    1. Das Feld requiredRevisionId wird 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 die 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 des Mitbearbeiters angewendet. Das Ergebnis der Schreibanfrage enthält sowohl die Änderungen aus der Schreibanfrage als auch die Änderungen des Mitbearbeiters in einer neuen Version des Dokuments. Der Docs-Server ist für das Zusammenführen der Inhalte verantwortlich.

Ein Beispiel dafür, wie Sie eine Batchanfrage mit WriteControl erstellen, finden Sie hier.

Tabs berücksichtigen

Ein einzelnes Dokument kann mehrere Tabs enthalten, die in Ihren API-Anfragen eine spezielle Verarbeitung erfordern.

Das sollten Sie beachten:

  1. Legen Sie den Parameter includeTabsContent in der Methode documents.get auf true fest, um den Inhalt aller Tabs in einem Dokument abzurufen. Standardmäßig werden nicht alle Tab-Inhalte zurückgegeben.
  2. Geben Sie in der Methode documents.batchUpdate die ID(s) der Tabs an, auf die die einzelnen Request angewendet werden sollen. Jede Request enthält eine Möglichkeit, die Tabs anzugeben, auf die die Aktualisierung angewendet werden soll. Wenn kein Tab angegeben ist, wird die Request in den meisten Fällen auf den ersten Tab im Dokument angewendet. Weitere Informationen finden Sie in der Dokumentation zu Request.