Method: documents.batchUpdate

Stosuje w dokumencie co najmniej 1 aktualizację.

Każda request jest weryfikowana przed zastosowaniem. Jeśli którekolwiek żądanie jest nieprawidłowe, całe żądanie zakończy się niepowodzeniem i nic nie zostanie zastosowane.

Niektóre prośby mają ikonę replies, która zawiera informacje o sposobie ich zastosowania. Inne żądania nie muszą zwracać informacji. W takich przypadkach zwracana jest pusta odpowiedź. Kolejność odpowiedzi jest taka sama jak kolejność żądań.

Załóżmy na przykład, że wywołujesz batchUpdate z 4 aktualizacjami, a tylko trzecia z nich zwraca informacje. Odpowiedź będzie zawierać 2 puste odpowiedzi, odpowiedź na trzecie żądanie i kolejną pustą odpowiedź w tej kolejności.

Ponieważ inni użytkownicy mogą edytować dokument, może on nie odzwierciedlać dokładnie Twoich zmian. Mogą one zostać zmodyfikowane w odniesieniu do zmian wprowadzonych przez współpracowników. Jeśli nie ma współpracowników, dokument powinien odzwierciedlać Twoje zmiany. W każdym przypadku zmiany w Twoim żądaniu zostaną zastosowane razem w sposób niepodzielny.

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
documentId

string

Identyfikator dokumentu do zaktualizowania.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Pola
requests[]

object (Request)

Lista aktualizacji, które mają zostać zastosowane w dokumencie.
writeControl

object (WriteControl)

Umożliwia kontrolowanie sposobu wykonywania żądań zapisu.

Treść odpowiedzi

Wiadomość z odpowiedzią na żądanie documents.batchUpdate.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
Pola
documentId

string

Identyfikator dokumentu, do którego zastosowano aktualizacje.
replies[]

object (Response)

Odpowiedź na aktualizacje. Jest to mapowanie 1:1 z aktualizacjami, chociaż odpowiedzi na niektóre żądania mogą być puste.
writeControl

object (WriteControl)

Zaktualizowana kontrola zapisu po zastosowaniu prośby.
suggestionResponses[]

object (SuggestionResponse)

Wskazówki, na które wpłynęła każda aktualizacja. Odpowiada to w pełni aktualizacjom.

commentUpdateState

enum (CommentUpdateState)

Informacja o tym, czy aktualizacje komentarzy zostały zastosowane w żądaniu zbiorczym.

Zakresy autoryzacji

Wymaga jednego z tych zakresów OAuth:

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

Więcej informacji znajdziesz w przewodniku po autoryzacji.

WriteControl

Umożliwia kontrolowanie sposobu wykonywania żądań zapisu.

Zapis JSON 
{
  "writeMode": enum (WriteMode),

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

enum (WriteMode)

Sposób zastosowania aktualizacji do dokumentu.

Jeśli nie zostanie określony, aktualizacje żądania zostaną zastosowane jako zwykłe zmiany.

Pole zbiorcze control. Określa wersję dokumentu, do której mają zostać zapisane zmiany, oraz sposób, w jaki żądanie powinno się zachowywać, jeśli ta wersja nie jest bieżącą wersją dokumentu. Jeśli nie podasz żadnego z tych pól, aktualizacje zostaną zastosowane do najnowszej wersji. control może mieć tylko jedną z tych wartości:
requiredRevisionId

string

Opcjonalny revision ID dokumentu, do którego stosowane jest żądanie zapisu. Jeśli nie jest to najnowsza wersja dokumentu, żądanie nie jest przetwarzane i zwraca błąd 400 (Nieprawidłowe żądanie).

Gdy w odpowiedzi zostanie zwrócony wymagany identyfikator wersji, oznacza to identyfikator wersji dokumentu po zastosowaniu żądania.
targetRevisionId

string

Opcjonalny cel revision ID dokumentu, do którego stosowane jest żądanie zapisu.

Jeśli po odczytaniu dokumentu za pomocą interfejsu API współpracownik wprowadził zmiany, zmiany wynikające z tej prośby o zapisanie zostaną zastosowane w odniesieniu do zmian wprowadzonych przez współpracownika. Spowoduje to utworzenie nowej wersji dokumentu, która będzie zawierać zarówno zmiany wprowadzone przez współpracownika, jak i zmiany w prośbie. Serwer Dokumentów rozwiąże konflikty. Gdy używasz identyfikatora wersji docelowej, klienta interfejsu API można traktować jako kolejnego współpracownika w dokumencie.

Identyfikator wersji docelowej można wykorzystać tylko do zapisywania w najnowszych wersjach dokumentu. Jeśli wersja docelowa jest zbyt daleko w tyle za najnowszą wersją, żądanie nie jest przetwarzane i zwracany jest błąd 400 (Nieprawidłowe żądanie). Po pobraniu najnowszej wersji dokumentu należy ponownie wysłać prośbę. Zwykle identyfikator wersji pozostaje ważny jako wersja docelowa przez kilka minut po odczytaniu, ale w przypadku często edytowanych dokumentów ten okres może być krótszy.

WriteMode

Określa, w jaki sposób aktualizacje żądań powinny być stosowane w dokumencie.

Wartości w polu enum
WRITE_MODE_UNSPECIFIED Tryb zapisu jest nieokreślony. Domyślnie działa jak EDIT.
EDIT Zastosuj wszystkie aktualizacje jako zwykłe zmiany.
SUGGEST Zastosuj wszystkie aktualizacje jako sugestie.

SuggestionResponse

sugestie, na które wpłynęła dana aktualizacja;

Zapis JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
Pola
createdSuggestionIds[]

string

Identyfikatory sugestii utworzonych podczas aktualizacji.
updatedSummarySuggestionIds[]

string

Identyfikatory sugestii, których podsumowania zostały zaktualizowane podczas aktualizacji.
deletedSuggestionIds[]

string

Identyfikatory sugestii, które zostały usunięte podczas aktualizacji.
acceptedSuggestionIds[]

string

Identyfikatory sugestii, które zostały zaakceptowane podczas aktualizacji.
rejectedSuggestionIds[]

string

Identyfikatory sugestii, które zostały odrzucone podczas aktualizacji.

CommentUpdateState

Stan aktualizacji komentarzy w żądaniu zbiorczym.

Wartości w polu enum
COMMENT_UPDATE_STATE_UNSPECIFIED Stan aktualizacji komentarzy jest nieokreślony.
NO_UPDATES_REQUESTED W żądaniu zbiorczym nie przesłano żadnych próśb o zaktualizowanie komentarzy.
ALL_SAVED W żądaniu zbiorczym zastosowano wszystkie aktualizacje komentarzy.
ALL_FAILED_UNKNOWN_REASON Nie udało się zaktualizować wszystkich żądanych komentarzy.