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 so angezeigt, wie Sie sie vorgenommen haben. Wenn keine Mitbearbeiter vorhanden sind, sollten Ihre Änderungen im Dokument angezeigt werden. 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 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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
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.
suggestionResponses[]

object (SuggestionResponse)

Die Vorschläge, die von den einzelnen Updates betroffen waren. Das entspricht 1:1 den Updates.

commentUpdateState

enum (CommentUpdateState)

Gibt an, ob Kommentaraktualisierungen in der Batchanfrage angewendet wurden.

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 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
Felder
writeMode

enum (WriteMode)

Wie die Aktualisierungen der Anfrage auf das Dokument angewendet werden sollen.

Wenn keine Angabe erfolgt, werden die Aktualisierungen der Anfrage als normale Änderungen angewendet.

Union-Feld control. Bestimmt die Version des Dokuments, in die geschrieben werden soll, und wie sich die Anfrage verhalten soll, wenn diese Version nicht die aktuelle Version 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 sich die Schreibanfrage bezieht. 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 erzeugten Ä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 alle Konflikte. 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 Zielversion zu weit hinter der neuesten Version liegt, wird die Anfrage nicht verarbeitet und es wird der Fehler „400 Bad Request“ 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.

WriteMode

Bestimmt, wie die Aktualisierungen der Anfrage auf das Dokument angewendet werden sollen.

Enums
WRITE_MODE_UNSPECIFIED Der Schreibmodus ist nicht angegeben. Die Standardeinstellung ist das Verhalten von EDIT.
EDIT Wenden Sie alle Updates als normale Änderungen an.
SUGGEST Alle Aktualisierungen als Vorschläge übernehmen.

SuggestionResponse

Die Vorschläge, die von einem bestimmten Update betroffen waren.

JSON-Darstellung 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
Felder
createdSuggestionIds[]

string

Die IDs der Vorschläge, die während des Updates erstellt wurden.
updatedSummarySuggestionIds[]

string

Die IDs der Vorschläge, deren Zusammenfassungen während des Updates aktualisiert wurden.
deletedSuggestionIds[]

string

Die IDs der Vorschläge, die während des Updates gelöscht wurden.
acceptedSuggestionIds[]

string

Die IDs der Vorschläge, die während des Updates akzeptiert wurden.
rejectedSuggestionIds[]

string

Die IDs der Vorschläge, die während des Updates abgelehnt wurden.

CommentUpdateState

Der Status von Kommentaraktualisierungen in der Batchanfrage.

Enums
COMMENT_UPDATE_STATE_UNSPECIFIED Der Status von Kommentaraktualisierungen ist nicht angegeben.
NO_UPDATES_REQUESTED In der Batchanfrage wurden keine Kommentaraktualisierungen angefordert.
ALL_SAVED Alle angeforderten Kommentaraktualisierungen wurden in der Batchanfrage angewendet.
ALL_FAILED_UNKNOWN_REASON Alle angeforderten Kommentaraktualisierungen sind fehlgeschlagen.