Method: documents.batchUpdate

Wendet eine oder mehrere Aktualisierungen auf das Dokument an.

Jeder request wird vor dem Anwenden validiert. Wenn eine Anfrage ungültig ist, schlägt die gesamte Anfrage fehl und es wird nichts angewendet.

Bei einigen Anfragen gibt es replies, damit Sie sehen, wie sie angewendet werden. Bei anderen Anfragen müssen keine Informationen zurückgegeben werden. Für jede Anfrage wird eine leere Antwort zurückgegeben. Die Reihenfolge der Antworten stimmt mit der der Anfragen überein.

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

Da andere Nutzer das Dokument möglicherweise bearbeiten, kann es vorkommen, dass das Dokument nicht unbedingt Ihre Änderungen wiedergibt: Ihre Änderungen können im Hinblick auf die von den Mitbearbeitern vorgenommenen Änderungen geändert werden. Wenn keine Mitbearbeiter vorhanden sind, sollte das Dokument Ihre Änderungen widerspiegeln. In jedem Fall werden die Aktualisierungen in Ihrer Anfrage garantiert atomar 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)

Steuert die Ausführung von Schreibanfragen.

Antworttext

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

Antwortnachricht einer documents.batchUpdate-Anfrage.

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 auf die Änderungen. Dies entspricht den Aktualisierungen 1:1. Die Antworten auf einige Anfragen sind möglicherweise leer.
writeControl

object (WriteControl)

Das aktualisierte Steuerelement für Schreibvorgänge 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 in der Übersicht zu OAuth 2.0.

Schreibkontrolle

Steuert die Ausführung von Schreibanfragen.

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. Bestimmt die Überarbeitung des Dokuments, in das geschrieben werden soll, und wie sich die Anfrage verhalten soll, wenn diese Überarbeitung nicht die aktuelle Überarbeitung des Dokuments ist. Wenn keines dieser Felder angegeben ist, werden 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 letzte Überarbeitung des Dokuments ist, wird die Anfrage nicht verarbeitet und der Fehler „400 bad request“ 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 erzeugten Änderungen auf die Änderungen des Mitbearbeiters 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, wobei der Google Docs-Server in Konflikt stehende Änderungen löst. Wenn Sie die Zielüberarbeitungs-ID verwenden, kann der API-Client als ein anderer Mitbearbeiter des Dokuments betrachtet werden.

Die Zielüberarbeitungs-ID kann nur zum Schreiben in die letzten Versionen eines Dokuments verwendet werden. Wenn die Zielüberarbeitung zu weit hinter der letzten Überarbeitung liegt, wird die Anfrage nicht verarbeitet und ein Fehler vom Typ „400 – Fehler“ zurückgegeben. Versuchen Sie es noch einmal, nachdem Sie die neueste Version des Dokuments abgerufen haben. In der Regel ist eine Überarbeitungs-ID nach dem Lesen einige Minuten lang als Zielüberarbeitung gültig. Bei häufig bearbeiteten Dokumenten kann dieses Fenster jedoch kürzer sein.