Sprawdzone metody uzyskiwania najlepszych wyników

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 sekcjach poniżej opisujemy te zasady.

Edytowanie wstecz w celu zwiększenia wydajności

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 spowodowanych wstawianiem i usuwaniem elementów.

Planowanie współpracy

Oczekuj zmiany stanu dokumentu. Pomiędzy wywołaniem jednej metody a inną inni współpracownicy mogą zaktualizować dokument, jak pokazano na diagramie poniżej:

Jak dokument może się zmieniać między wywołaniami metody.

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ć tymi ustawieniami 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.

Aby to zrobić:

  1. Pobierz dokument za pomocą metody documents.get i zapisz obiekt revisionId ze zwróconego zasobu documents.
  2. Tworzenie próśb o aktualizację.
  3. Dodaj opcjonalny obiekt WriteControl z 1 z 2 opcji:
    1. Pole requiredRevisionId jest ustawione na revisionId 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.
    2. Pole targetRevisionId jest ustawione na revisionId 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.

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ą określonej obsługi żądań do interfejsu API.

Pamiętaj o tym:

  1. Aby pobrać zawartość ze wszystkich kart w dokumencie, w metodzie documents.get ustaw parametr includeTabsContent na true. Domyślnie zwracane są nie wszystkie treści kart.
  2. Określ identyfikatory kart, do których mają zostać zastosowane poszczególne Request w metodzie documents.batchUpdate. Każdy element Request 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 użyta karta Request w pierwszym dokumencie. Szczegółowe informacje znajdziesz w dokumentacji Request.