Method: documents.batchUpdate

Wendet eine oder mehrere Aktualisierungen auf das Dokument an.

Jede request wird vor der Anwendung validiert. Wenn eine Anfrage ungültig ist, schlägt die gesamte Anfrage fehl und es werden keine Änderungen vorgenommen.

Einige Anfragen haben replies, um Ihnen Informationen zur Anwendung zu geben. Bei anderen Anfragen müssen keine Informationen zurückgegeben werden. Für diese Anfragen wird jeweils eine leere Antwort zurückgegeben. Die Reihenfolge der Antworten entspricht der Reihenfolge der Anfragen.

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

Da andere Nutzer das Dokument möglicherweise bearbeiten, spiegelt es möglicherweise nicht genau Ihre Änderungen wider. Ihre Änderungen werden möglicherweise im Hinblick auf die Änderungen der Mitbearbeiter geändert. Wenn es keine Mitbearbeiter gibt, sollten Ihre Änderungen im Dokument berücksichtigt werden. In jedem Fall werden die Aktualisierungen in Ihrer Anfrage garantiert gemeinsam in kleinstmöglichen Schritten 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 Änderungen, die auf das Dokument angewendet werden sollen.
writeControl

object (WriteControl)

Steuert, 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 Änderungen angewendet wurden.
replies[]

object (Response)

Die Antwort auf die Aktualisierungen. Die Zuordnung erfolgt 1:1 mit den Updates, auch wenn Antworten auf einige Anfragen leer sein können.
writeControl

object (WriteControl)

Die aktualisierte Schreibsteuerung 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.

WriteControl

Steuert, 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. Bestimmt die Version des Dokuments, in das geschrieben werden soll, und wie sich die Anfrage verhalten soll, wenn diese Version nicht die aktuelle Version des Dokuments ist. Wenn kein Feld angegeben ist, werden Aktualisierungen auf die neueste Version 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 neueste Version des Dokuments ist, wird die Anfrage nicht verarbeitet und es wird der Fehler 400 (ungültige Anfrage) zurückgegeben.

Wenn in einer Antwort eine erforderliche Versions-ID zurückgegeben wird, gibt sie die Versions-ID des Dokuments nach Anwendung der Anfrage an.
targetRevisionId

string

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

Wenn Mitbearbeiter nach dem Lesen des Dokuments mit der API Änderungen vorgenommen haben, werden die Änderungen, die durch diese Schreibanfrage vorgenommen wurden, auf die Änderungen der Mitbearbeiter angewendet. Das führt zu einer neuen Version des Dokuments, die sowohl die Änderungen der Mitbearbeiter als auch die Änderungen in der Anfrage enthält. Der Docs-Server löst dabei in Konflikt stehende Änderungen. Wenn die Zielversions-ID verwendet wird, kann der API-Client als weiterer Mitbearbeiter des Dokuments betrachtet werden.

Die Zielüberarbeitungs-ID kann nur zum Schreiben in aktuelle Versionen eines Dokuments verwendet werden. Wenn die Zielversion zu weit hinter der neuesten Version liegt, wird die Anfrage nicht verarbeitet und es wird der Fehler 400 zurückgegeben. Versuchen Sie es noch einmal, nachdem Sie die neueste Version des Dokuments abgerufen haben. Normalerweise bleibt eine Versions-ID nach dem Lesen noch einige Minuten lang gültig, um als Zielversion verwendet zu werden. Bei häufig bearbeiteten Dokumenten kann dieses Zeitfenster jedoch kürzer sein.