Method: documents.batchUpdate

Wendet eine oder mehrere Aktualisierungen auf das Dokument an.

Jede request muss vor der Anwendung validiert werden. Wenn eine Anfrage ungültig ist, schlägt die gesamte Anfrage fehl und es wird nichts angewendet.

Bei einigen Anfragen gibt es replies, um Ihnen Informationen zur Anwendung zu geben. Bei anderen Anfragen müssen keine Informationen zurückgegeben werden, da sie jeweils eine leere Antwort zurückgeben. Die Reihenfolge der Antworten stimmt mit der der Anfragen überein.

Beispiel: Sie rufen „BatchUpdate“ mit vier Updates auf und nur das dritte gibt Informationen zurück. Die Antwort enthält zwei leere Antworten, die dritte auf die dritte Anfrage, und eine weitere leere Antwort in dieser Reihenfolge.

Da das Dokument möglicherweise von anderen Nutzern bearbeitet wird, spiegelt das Dokument Ihre Änderungen möglicherweise nicht genau wider. Ihre Änderungen können im Hinblick auf die Änderungen von Mitbearbeitern geändert werden. Wenn keine Mitbearbeiter vorhanden sind, sollten die Änderungen im Dokument widergespiegelt werden. In jedem Fall werden die Aktualisierungen in Ihrer Anfrage garantiert einheitlich angewendet.

HTTP-Anfrage

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
documentId

string

Die ID des Dokuments, das aktualisiert werden soll.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Felder
requests[]

object (Request)

Eine Liste der Aktualisierungen, die auf das Dokument angewendet werden sollen.

writeControl

object (WriteControl)

Hiermit wird gesteuert, wie Schreibanfragen ausgeführt werden.

Antworttext

Antwortnachricht von einer documents.batchUpdate-Anfrage.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Felder
documentId

string

Die ID des Dokuments, auf das die Aktualisierungen angewendet wurden.

replies[]

object (Response)

Die Antwort zu den Updates. Diese Karte wird zu 1:1 zugeordnet und die Antworten können leer sein.

writeControl

object (WriteControl)

Das aktualisierte Schreibsteuerelement nach Anwendung der Anfrage.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

Weitere Informationen finden Sie im Leitfaden zur Autorisierung.

Schreibsteuerung

Hiermit wird gesteuert, wie Schreibanfragen ausgeführt werden.

JSON-Darstellung
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
Felder
Union-Feld control. Legt die Überarbeitung des Dokuments fest, in das geschrieben werden soll, und wie sich die Anfrage verhält, wenn diese Überarbeitung nicht die aktuelle Überarbeitung des Dokuments ist. Ist kein Feld angegeben, werden die Aktualisierungen auf die letzte Überarbeitung angewendet. Für control ist nur einer der folgenden Werte zulässig:
requiredRevisionId

string

Die optionale revision ID des Dokuments, auf das die Schreibanfrage angewendet wird. Wenn dies nicht die aktuelle Überarbeitung des Dokuments ist, wird die Anfrage nicht verarbeitet und der Fehler 400 wird zurückgegeben.

Wenn eine erforderliche Überarbeitungs-ID in einer Antwort zurückgegeben wird, gibt sie die Überarbeitungs-ID des Dokuments an, nachdem die Anfrage angewendet wurde.

targetRevisionId

string

Das optionale Ziel revision ID des Dokuments, auf das die Schreibanfrage angewendet wird.

Wenn Mitbearbeiteränderungen vorgenommen wurden, nachdem das Dokument mit der API gelesen wurde, werden die durch diese Schreibanfrage generierten Änderungen auf diese Mitbearbeiteränderungen angewendet. Das führt zu einer neuen Überarbeitung des Dokuments, das sowohl die Änderungen der Mitbearbeiter als auch die Änderungen in der Anfrage enthält. Der Docs-Server löst in Konflikt stehende Änderungen auf. Bei Verwendung der Zielüberarbeitungs-ID kann der API-Client als ein weiterer Mitbearbeiter des Dokuments betrachtet werden.

Die ID der Zielüberarbeitung kann nur zum Schreiben in aktuelle Versionen eines Dokuments verwendet werden. Wenn die Zielüberarbeitung zu weit hinter der letzten Überarbeitung zurückliegt, wird die Anfrage nicht verarbeitet und der Fehler 400 wird zurückgegeben. Versuchen Sie es noch einmal, nachdem Sie die neueste Version des Dokuments abgerufen haben. In der Regel bleibt eine Überarbeitungs-ID für einige Minuten nach dem Lesen als Zielüberarbeitung. Für häufig bearbeitete Dokumente kann dieses Fenster aber kürzer sein.