Podczas korzystania z interfejsu API Dokumentów Google musisz przestrzegać kilku zasad. Obejmują one:
- Edytuj wstecz, aby zwiększyć wydajność
- Planowanie współpracy
- Zapewnij spójność stanów za pomocą
WriteControl
pole - Uwzględniaj karty
W sekcjach poniżej opisujemy te zasady.
Edytuj wstecz, aby zwiększyć wydajność
W ramach jednego wywołania
documents.batchUpdate
uporządkuj żądania w
w kolejności malejącej lokalizacji indeksu. Eliminuje to konieczność obliczania wartości
zmian indeksu w wyniku wstawienia i usunięcia.
Planowanie współpracy
Oczekuj zmiany stanu dokumentu. Między wywołaniem jednej metody a drugą współpracownicy mogą aktualizować dokument, co pokazuje następujący diagram:
Jeśli indeksy będą nieprawidłowe, może to prowadzić do błędów. Gdy wielu użytkowników edytuje
za pomocą interfejsu użytkownika, Dokumenty Google zrobią to w sposób przejrzysty. Pamiętaj jednak:
jako klienta interfejsu API,
czyli aplikacja musi nim zarządzać. Nawet jeśli nie spodziewasz się,
nad dokumentem, ważne jest, aby zaprogramować obronę i zapewnić
aby zapewnić spójny stan dokumentu. Aby zapewnić spójność,
zapoznaj się z sekcją WriteControl
.
Ustalenie spójności stanów za pomocą funkcji WriteControl
Czytając i aktualizując dokument, możesz kontrolować sposób, w jaki
zmiany konkurujące są obsługiwane za pomocą
WriteControl
w metodzie documents.batchUpdate
. WriteControl
zapewnia uprawnienia
nad sposobem wykonywania żądań zapisu.
Aby to zrobić:
- Pobierz dokument za pomocą
documents.get
i zapiszrevisionId
ze zwróconego zasobudocuments
. - Utwórz prośby o aktualizację.
- Dołącz opcjonalny element
WriteControl
. możesz wybrać jedną z dwóch opcji:- Pole
requiredRevisionId
jest ustawione narevisionId
klucza dokument, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany ponieważ zrealizowano żądanie odczytu interfejsu API, żądanie zapisu nie jest przetwarzane i zwraca błąd. - Pole
targetRevisionId
jest ustawione narevisionId
dokumentu do których ma zastosowanie żądanie zapisu. Jeśli dokument został zmodyfikowany od API odczytu, zmiany w żądaniu zapisu są stosowane do klasy zmiany wprowadzone przez współpracowników. Wynik żądania zapisu zawiera zarówno żądanie zapisu zmieni się, a współpracownik zmieni się w nowy wersji dokumentu. Serwer Dokumentów odpowiada za to przeznaczonego do scalenia treści.
- Pole
Przykład tworzenia żądania zbiorczego za pomocą funkcji WriteControl
znajdziesz tutaj
ten przykład żądania zbiorczego.
Uwzględniaj karty
Pojedynczy dokument może zawierać wiele kart, które wymagają specjalnej obsługi w żądaniach do interfejsu API.
Oto, o czym należy pamiętać:
- Ustaw parametr
includeTabsContent
natrue
wdocuments.get
do pobiera treść ze wszystkich kart w dokumencie. Domyślnie nie wszystkie karty . - Podaj identyfikatory kart, które mają być stosowane do poszczególnych elementów
Request
do wdocuments.batchUpdate
. CoRequest
umożliwia określenie kart, do których ma zostać zastosowana aktualizacja. Domyślnie, jeśli nie określono znaku tabulacji,Request
w większości przypadków zostanie zastosowana na pierwszej karcie dokumentu. Zapoznaj się zRequest
s dokumentację.