Podczas korzystania z interfejsu API Dokumentów Google musisz przestrzegać kilku zasad. Są to między innymi:
- Edytuj wstecz, aby zwiększyć wydajność
- Planowanie współpracy
- Zapewnienie spójności stanów za pomocą pola
WriteControl
W sekcjach poniżej opisujemy te zasady.
Edytuj wstecz, aby zwiększyć wydajność
W ramach pojedynczego wywołania metody documents.batchUpdate
uporządkuj żądania w kolejności malejącej od lokalizacji indeksu. Dzięki temu nie trzeba obliczać zmian indeksu wynikających z wstawienia lub usuwania.
Planowanie współpracy
Oczekuj zmiany stanu dokumentu. Między wywołaniem jednej metody a drugą inni współpracownicy mogą aktualizować dokument, tak jak na tym schemacie:
Jeśli indeksy będą nieprawidłowe, może to prowadzić do błędów. Gdy wielu użytkowników edytuje dokument za pomocą
interfejsu, Dokumenty Google zajmują się tym w przejrzysty sposób. Jednak jako klient interfejsu API musi tym zarządzać aplikacja. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest odpowiednie obrony i zapewnienie spójnego stanu dokumentu. Aby uzyskać spójność, zapoznaj się z sekcją WriteControl
.
Ustalenie spójności stanów za pomocą funkcji WriteControl
Gdy odczytasz, a następnie zaktualizujesz dokument, możesz kontrolować sposób obsługi zmian konkurujących za pomocą pola WriteControl
w metodzie documents.batchUpdate
. WriteControl
kontroluje sposób wykonywania żądań zapisu.
Aby to zrobić:
- Pobierz dokument za pomocą metody
documents.get
i zapisz obiektrevisionId
ze zwróconego zasobudocuments
. - Utwórz prośby o aktualizację.
- Dodaj opcjonalny obiekt
WriteControl
z 1 z 2 opcji:- Pole
requiredRevisionId
jest ustawione narevisionId
dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od momentu przesłania żądania odczytu z 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 są stosowane względem zmian partnera. Wynik żądania zapisu uwzględnia zarówno zmiany żądania zapisu, jak i zmiany współpracownika w nowej wersji dokumentu. Serwer Dokumentów odpowiada za scalanie treści.
- Pole
Przykład tworzenia żądania zbiorczego za pomocą WriteControl
znajdziesz w tym przykładzie żądania zbiorczego.