Podczas korzystania z interfejsu Google Docs API należy przestrzegać kilku zasad. Obejmują one:
- Edytowanie wstecz w celu zwiększenia wydajności
- Planowanie współpracy
- Zapewnienie spójności stanu za pomocą pola
WriteControl
- Uwzględnij karty
W następnych sekcjach omawiamy te zasady.
Edytowanie wstecz w celu zwiększenia wydajności
W ramach jednego wywołania metody documents.batchUpdate
ułóż żądania w malejącym porządku według położenia indeksu. Dzięki temu nie trzeba obliczać zmian indeksu spowodowanych wstawianiem i usuwaniem elementów.
Planowanie współpracy
Stan dokumentu może się zmienić. Pomiędzy wywołaniem jednej metody a inną inni współpracownicy mogą zaktualizować dokument, jak pokazano na diagramie poniżej:
Może to prowadzić do błędów, jeśli indeksy są nieprawidłowe. Gdy wielu użytkowników edytuje dokument za pomocą interfejsu, Dokumenty Google zajmują się tym w sposób przejrzysty. Jednak jako klient interfejsu API musisz zarządzać tym w swojej aplikacji. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest, aby zabezpieczyć program i zadbać o to, aby stan dokumentu był spójny. Aby zapewnić spójność, zapoznaj się z sekcją WriteControl
.
Utrzymywanie spójności stanu za pomocą WriteControl
Gdy czytasz i aktualizujesz dokument, możesz kontrolować sposób obsługi konfliktują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
z zwróconego zasobudocuments
. - Tworzenie próśb o aktualizację.
- Dodaj opcjonalny obiekt
WriteControl
, wybierając jedną z tych opcji:- Pole
requiredRevisionId
jest ustawione narevisionId
dokumentu, do którego ma zastosowanie żądanie zapisu. Jeśli dokument został zmodyfikowany od momentu wysłania żądania odczytu interfejsu API, żądanie zapisu nie zostanie przetworzone i zwróci błąd. - Pole
targetRevisionId
jest ustawione narevisionId
dokumentu, do którego ma zastosowanie żądanie zapisu. Jeśli dokument został zmodyfikowany od momentu wysłania żądania odczytu interfejsu API, zmiany żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracownika. Wynik prośby o zapisanie obejmuje zarówno zmiany w prośbie o zapisanie, jak i zmiany wprowadzone przez współpracownika w nowej wersji dokumentu. Serwer Dokumentów odpowiada za scalanie treści.
- Pole
Przykładowy sposób tworzenia żądania zbiorczego za pomocą WriteControl
znajdziesz w przykładowym żądaniu zbiorczym.
Uwzględnij karty
Pojedynczy dokument może zawierać wiele kart, które wymagają specjalnego przetwarzania w żądaniach interfejsu API.
Pamiętaj o tym:
- Aby pobrać zawartość ze wszystkich kart w dokumencie, w metodzie
documents.get
ustaw parametrincludeTabsContent
natrue
. Domyślnie zwracane są nie wszystkie treści kart. - Określ identyfikatory kart, aby zastosować każdą z nich
Request
documents.batchUpdate
metodą. Każdy elementRequest
umożliwia określenie kart, na których ma zostać zastosowana aktualizacja. Jeśli nie określisz karty, domyślnie w większości przypadków zostanie zastosowana kartaRequest
do pierwszej karty w dokumencie. Szczegółowe informacje znajdziesz w dokumentacjiRequest
.