Sprawdzone metody uzyskiwania najlepszych wyników

Podczas korzystania z interfejsu Google Docs API należy przestrzegać kilku zasad. Są to między innymi:

  • Edytuj od końca, aby zwiększyć wydajność
  • Planowanie współpracy
  • Zapewnianie spójności stanu za pomocą pola WriteControl
  • Uwzględnianie kart

W sekcjach poniżej wyjaśniamy te zasady.

Edytuj od końca, aby zwiększyć wydajność

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

Planowanie współpracy

Spodziewaj się zmiany stanu dokumentu. Między wywołaniami jednej metody a wywołaniami innej metody inni współpracownicy mogą aktualizować 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 w interfejsie, Dokumenty Google robią to w sposób przejrzysty. Jednak jako klient interfejsu API Twoja aplikacja musi zarządzać tym procesem. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest, aby zaprogramować go w sposób defensywny i zapewnić spójność stanu dokumentu. Aby dowiedzieć się, jak zapewnić spójność, zapoznaj się z sekcją WriteControl.

Zapewnianie spójności stanu za pomocą WriteControl

Podczas odczytywania, a następnie aktualizowania dokumentu możesz kontrolować sposób obsługi konkurencyjnych zmian za pomocą pola WriteControl 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 zasobu documents.
  2. Utwórz prośby o aktualizację.
  3. Dołącz opcjonalny obiekt WriteControl z jedną z tych 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 z interfejsu API, żądanie zapisu nie jest przetwarzane i zwraca błąd.
    2. Pole targetRevisionId jest ustawione na revisionId dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu wysłania żądania odczytu z interfejsu API, zmiany z żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracownika. Wynik żądania zapisu obejmuje zarówno zmiany wprowadzone w ramach żądania zapisu, jak i zmiany wprowadzone przez współpracownika w nowej wersji dokumentu. Serwer Dokumentów jest odpowiedzialny za scalanie treści.

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ą specjalnego traktowania w żądaniach API.

Oto o czym warto pamiętać:

  1. Ustaw parametr includeTabsContent na true w metodzie documents.get, aby pobrać zawartość ze wszystkich kart w dokumencie. Domyślnie nie są zwracane wszystkie treści kart.
  2. W metodzie documents.batchUpdate podaj identyfikatory kart, do których chcesz zastosować każdy element Request. Każda z nichRequest zawiera sposób określania kart, do których ma być zastosowana aktualizacja. Domyślnie, jeśli karta nie jest określona, Request w większości przypadków zostanie zastosowany do pierwszej karty w dokumencie. Szczegółowe informacje znajdziesz w dokumentacji Request.