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 wird nichts angewendet.

Einige Anfragen haben replies, um Ihnen Informationen zur Anwendung zu geben. Bei anderen Anfragen müssen keine Informationen zurückgegeben werden. In diesen Fällen 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 zwei leere Antworten, die Antwort auf die dritte Anfrage und eine weitere leere Antwort in dieser Reihenfolge enthalten.

Da andere Nutzer das Dokument möglicherweise bearbeiten, werden Ihre Änderungen möglicherweise nicht genau wiedergegeben. Sie können sich von den Änderungen der Mitbearbeiter unterscheiden. Wenn keine Mitbearbeiter vorhanden sind, sollten Ihre Änderungen im Dokument angezeigt werden. In jedem Fall werden die Aktualisierungen in Ihrer Anfrage garantiert untrennbar zusammen 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 zu aktualisierenden Dokuments.

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)

Bietet Kontrolle darüber, wie Schreibanfragen ausgeführt werden.

Antworttext

Antwortnachricht auf eine 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 auf die Updates. Dies entspricht 1:1 den Updates, obwohl 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 Autorisierungsleitfaden.

WriteControl

Bietet Kontrolle darüber, 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 Revision des Dokuments, in die geschrieben werden soll, und wie sich die Anfrage verhalten soll, wenn diese Revision nicht die aktuelle Revision des Dokuments ist. Wenn keines der beiden Felder angegeben ist, werden Aktualisierungen auf die aktuelle 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 es sich nicht um die aktuelle Version des Dokuments handelt, wird die Anfrage nicht verarbeitet und es wird der Fehler „400 Bad Request“ zurückgegeben.

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

string

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

Wenn nach dem Lesen des Dokuments über die API Änderungen durch Mitbearbeiter vorgenommen wurden, werden die durch diese Schreibanfrage erstellten Änderungen auf die Änderungen der Mitbearbeiter angewendet. Dadurch wird eine neue Überarbeitung des Dokuments erstellt, die sowohl die Änderungen des Mitbearbeiters als auch die Änderungen in der Anfrage enthält. Der Docs-Server löst dabei widersprüchliche Änderungen auf. Bei Verwendung der Zielversions-ID kann der API-Client als weiterer Mitbearbeiter des Dokuments betrachtet werden.

Die Zielversions-ID kann nur zum Schreiben in aktuelle Versionen eines Dokuments verwendet werden. Wenn die Zielrevision zu weit hinter der neuesten Revision liegt, wird die Anfrage nicht verarbeitet und es wird der Fehler „400-Fehler – ungültige Anfrage“ zurückgegeben. Die Anfrage sollte nach dem Abrufen der neuesten Version des Dokuments noch einmal versucht werden. Normalerweise bleibt eine Revisions-ID nach dem Lesen noch einige Minuten lang als Zielrevision gültig. Bei häufig bearbeiteten Dokumenten kann dieser Zeitraum jedoch kürzer sein.