Sprawdzone metody uzyskiwania najlepszych wyników

Podczas korzystania z interfejsu Google Docs API należy przestrzegać kilku zasad. Obejmują one:

  • Edytowanie od końca w celu zwiększenia wydajności
  • Planowanie współpracy
  • Zapewnianie spójności stanu za pomocą pola WriteControl
  • Uwzględnianie kart

Więcej informacji o tych zasadach znajdziesz w kolejnych sekcjach.

Edytowanie od końca w celu zwiększenia wydajności

W ramach jednego wywołania metody documents.batchUpdate uporządkuj żądania w kolejności malejącej według lokalizacji indeksu. Eliminuje to konieczność obliczania zmian indeksu spowodowanych wstawieniami i usunięciami.

Planowanie współpracy

Spodziewaj się, że stan dokumentu się zmieni. Między jednym wywołaniem metody a drugim inni współpracownicy mogą zaktualizować dokument, jak pokazano na tym diagramie:

Jak dokument może się zmienić między wywołaniami metod.

Jeśli indeksy są 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 sposób niewidoczny. Jednak jako klient interfejsu API Twoja aplikacja musi zarządzać tym samodzielnie. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest, aby programować defensywnie i dbać o spójność stanu dokumentu. Aby dowiedzieć się, jak zapewnić spójność, zapoznaj się z sekcją WriteControl.

Zapewnianie spójności stanu za pomocą WriteControl

Gdy odczytujesz, a potem aktualizujesz dokument, możesz kontrolować sposób obsługi konkurencyjnych zmian za pomocą WriteControl pola w metodzie documents.batchUpdate. WriteControl zapewnia kontrolę nad sposobem wykonywania żądań zapisu.

Oto jak go używać:

  1. Pobierz dokument za pomocą metody documents.get i zapisz revisionId z zwróconego documents zasobu.
  2. Utwórz żądania aktualizacji.
  3. Dołącz opcjonalny WriteControl obiekt z jedną z 2 opcji:
    1. Pole requiredRevisionId jest ustawione na revisionId dokumentu, do którego stosowane jest żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu wysłania żądania odczytu do interfejsu API, żądanie zapisu nie zostanie przetworzone i zwróci błąd.
    2. Pole targetRevisionId jest ustawione na revisionId dokumentu, do którego stosowane jest żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu wysłania żądania odczytu do interfejsu API, zmiany wprowadzone w żądaniu zapisu zostaną zastosowane do zmian wprowadzonych przez współpracownika. Wynik żądania zapisu obejmuje zarówno zmiany wprowadzone w żądaniu zapisu, jak i zmiany wprowadzone przez współpracownika w nowej wersji dokumentu. Za scalanie treści odpowiada serwer Dokumentów.

Przykład tworzenia żądania zbiorczego za pomocą WriteControl znajdziesz w tym przykładzie żądania zbiorczego.

Uwzględnianie kart

Jeden dokument może zawierać wiele kart, które wymagają specjalnej obsługi w żądaniach do interfejsu API.

Oto, o czym należy pamiętać:

  1. Ustaw parametr includeTabsContent na true w metodzie documents.get , aby pobrać zawartość wszystkich kart w dokumencie. Domyślnie nie jest zwracana cała zawartość karty.
  2. W metodzie określ identyfikatory kart, do których ma być stosowane każde Request do w documents.batchUpdate. Każde Request zawiera sposób określania kart, do których ma być stosowana aktualizacja. Domyślnie, jeśli karta nie jest określona, Request zostanie w większości przypadków zastosowane do pierwszej karty w dokumencie. Szczegółowe informacje znajdziesz w dokumentacji Requests.