Sprawdzone metody uzyskiwania najlepszych wyników

Podczas korzystania z interfejsu API Dokumentów Google musisz przestrzegać kilku zasad. Są to między innymi:

  • Edytuj wstecz, aby zwiększyć wydajność
  • Planuj współpracę
  • Zapewnij spójność stanu za pomocą pola WriteControl

W poniższych sekcjach opisano te zasady.

Edytuj wstecz, aby zwiększyć wydajność

W ramach pojedynczego wywołania metody documents.batchUpdate uporządkuj żądania w kolejności malejącej według lokalizacji indeksu. Dzięki temu nie trzeba obliczać zmian w indeksie z powodu wstawiania i usuwania.

Planuj współpracę

Pamiętaj, że stan dokumentu ulegnie zmianie. Między wywołaniem jednej metody a drugim 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, mogą wystąpić błędy. Ponieważ wielu użytkowników edytuje dokument za pomocą interfejsu, Dokumenty Google dbają o to w przejrzysty sposób. Jednak jako klient API Twoja aplikacja musi nimi zarządzać. Nawet jeśli nie przewidujesz współpracy nad dokumentem, pamiętaj, aby programować go w sposób defensywny i dbać o spójność stanu dokumentu. Informacje o sposobie zachowania spójności znajdziesz w sekcji WriteControl.

Ustal spójność stanu za pomocą parametru ReadControl

Odczytując i aktualizując dokument, możesz kontrolować sposób obsługi konkurujących zmian za pomocą pola WriteControl w metodzie documents.batchUpdate. WriteControl określa sposób wykonywania żądań zapisu.

Oto jak go używać:

  1. Pobierz dokument za pomocą metody documents.get i zapisz revisionId ze zwróconego zasobu documents.
  2. Utwórz prośby o aktualizację.
  3. Dodaj opcjonalny obiekt WriteControl na 1 z 2 opcji:
    1. Pole requiredRevisionId jest ustawione na revisionId dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany po otrzymaniu żą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 zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu żądania odczytu interfejsu API, zmiany żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracowników. Wynik żądania zapisu zawiera zmiany wprowadzone w żądaniu zapisu i zmiany wprowadzone przez współpracowników w nowej wersji dokumentu. Serwer Dokumentów odpowiada za scalenie treści.

Przykład tworzenia żądania zbiorczego za pomocą metody WriteControl znajdziesz w tym przykładowym żądaniu zbiorczym.