Best Practices für optimale Ergebnisse

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

  • Rückwärts bearbeiten, um Zeit zu sparen
  • Zusammenarbeit planen
  • Verwenden Sie das Feld WriteControl, um Statuskonsistenz zu gewährleisten.
  • Tabs berücksichtigen

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 müssen die Indexänderungen aufgrund von Einfügungen und Löschungen nicht berechnet werden.

Zusammenarbeit planen

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

Wie sich ein Dokument zwischen den 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 App dies jedoch verwalten. Auch wenn Sie nicht davon ausgehen, dass an dem Dokument zusammengearbeitet wird, ist es wichtig, proaktiv zu programmieren und dafür zu sorgen, dass der Dokumentstatus konsistent bleibt. Im Abschnitt WriteControl finden Sie eine Möglichkeit, für Einheitlichkeit zu sorgen.

Zustandskonsistenz mit WriteControl herstellen

Wenn Sie ein Dokument lesen und dann aktualisieren, können Sie mit dem Feld WriteControl in der documents.batchUpdate-Methode festlegen, wie konkurrierende Änderungen behandelt werden. WriteControl gibt Aufschluss darüber, wie Schreibanfragen ausgeführt werden.

So verwenden Sie die Funktion:

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

Ein Beispiel für die Erstellung einer Batchanfrage mit WriteControl finden Sie hier.

Tabs berücksichtigen

Ein einzelnes Dokument kann mehrere Tabs enthalten, die in Ihren API-Anfragen speziell behandelt werden müssen.

Folgendes solltest du 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 Tabinhalte zurückgegeben.
  2. Geben Sie in der Methode documents.batchUpdate die ID(s) der Tabs an, auf die die einzelnen Request angewendet werden sollen. Bei jeder Request können Sie angeben, auf welche Tabs die Aktualisierung angewendet werden soll. Wenn kein Tab angegeben ist, wird Request in den meisten Fällen auf den ersten Tab im Dokument angewendet. Weitere Informationen finden Sie in der Dokumentation zu Request.