Method: documents.batchUpdate

Stosuje do dokumentu co najmniej jedną 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 zgodna z kolejnością żą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ć zmienione 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 do zastosowania 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 żądania.
suggestionResponses[]

object (SuggestionResponse)

Sugestie, na które wpłynęła każda aktualizacja. Odpowiada to aktualizacjom w stosunku 1:1.
commentUpdateState

enum (CommentUpdateState)

Informacja o tym, czy w żądaniu zbiorczym zastosowano aktualizacje komentarzy.

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.
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 określisz żadnego z tych pól, aktualizacje zostaną zastosowane do najnowszej wersji. Poniżej znajduje się lista pól, które się wzajemnie wykluczają. W odpowiedzi zostanie ustawione co najwyżej jedno z tych pól:
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 tego żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracownika. Powoduje to utworzenie nowej wersji dokumentu, która zawiera zarówno zmiany wprowadzone przez współpracownika, jak i zmiany w prośbie. Serwer Dokumentów rozwiązuje konflikty między zmianami. Gdy używasz docelowego identyfikatora wersji, klienta API można traktować jako kolejnego współpracownika dokumentu.

Identyfikator wersji docelowej może być używany tylko do zapisywania w najnowszych wersjach dokumentu. Jeśli wersja docelowa jest zbyt stara w porównaniu z najnowszą wersją, żądanie nie jest przetwarzane i zwracany jest błąd 400 (nieprawidłowe żądanie). Po pobraniu najnowszej wersji dokumentu należy ponownie spróbować 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.
Koniec pól wykluczających się nawzajem.

WriteMode

Określa, jak 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 zażądano żadnych aktualizacji komentarzy.
ALL_SAVED W żądaniu zbiorczym zastosowano wszystkie żądane aktualizacje komentarzy.
ALL_FAILED_UNKNOWN_REASON Nie udało się zaktualizować wszystkich komentarzy.