Podczas korzystania z interfejsu API Dokumentów Google musisz przestrzegać kilku zasad. Są to między innymi:
- Edytuj wstecz, aby zwiększyć wydajność
- Planuj współpracę
- Zapewnij spójność stanu za pomocą pola
WriteControl
W poniższych sekcjach opisano te zasady.
Edytuj wstecz, aby zwiększyć wydajność
W ramach pojedynczego wywołania metody documents.batchUpdate
uporządkuj żądania w kolejności malejącej według lokalizacji indeksu. Dzięki temu nie trzeba obliczać zmian w indeksie z powodu wstawiania i usuwania.
Planuj współpracę
Pamiętaj, że stan dokumentu ulegnie zmianie. Między wywołaniem jednej metody a drugim inni współpracownicy mogą aktualizować dokument, jak pokazano na tym diagramie:
Jeśli indeksy są nieprawidłowe, mogą wystąpić błędy. Ponieważ wielu użytkowników edytuje dokument za pomocą interfejsu, Dokumenty Google dbają o to w przejrzysty sposób. Jednak jako klient API Twoja aplikacja musi nimi zarządzać. Nawet jeśli nie przewidujesz współpracy nad dokumentem, pamiętaj, aby programować go w sposób defensywny i dbać o spójność stanu dokumentu. Informacje o sposobie zachowania spójności znajdziesz w sekcji WriteControl
.
Ustal spójność stanu za pomocą parametru ReadControl
Odczytując i aktualizując dokument, możesz kontrolować sposób obsługi konkurujących zmian za pomocą pola WriteControl
w metodzie documents.batchUpdate
. WriteControl
określa sposób wykonywania żądań zapisu.
Oto jak go używać:
- Pobierz dokument za pomocą metody
documents.get
i zapiszrevisionId
ze zwróconego zasobudocuments
. - Utwórz prośby o aktualizację.
- Dodaj opcjonalny obiekt
WriteControl
na 1 z 2 opcji:- Pole
requiredRevisionId
jest ustawione narevisionId
dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany po otrzymaniu żądania odczytu interfejsu API, żądanie zapisu nie zostanie przetworzone i zwróci błąd. - Pole
targetRevisionId
jest ustawione narevisionId
dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu żądania odczytu interfejsu API, zmiany żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracowników. Wynik żądania zapisu zawiera zmiany wprowadzone w żądaniu zapisu i zmiany wprowadzone przez współpracowników w nowej wersji dokumentu. Serwer Dokumentów odpowiada za scalenie treści.
- Pole
Przykład tworzenia żądania zbiorczego za pomocą metody WriteControl
znajdziesz w tym przykładowym żądaniu zbiorczym.