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ść
  • Planowanie współpracy
  • Zapewnienie spójności stanów za pomocą pola WriteControl

W sekcjach poniżej opisujemy te zasady.

Edytuj wstecz, aby zwiększyć wydajność

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 wynikających z wstawienia lub usuwania.

Planowanie współpracy

Oczekuj zmiany stanu dokumentu. Między wywołaniem jednej metody a drugą inni współpracownicy mogą aktualizować dokument, tak jak na tym schemacie:

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

Jeśli indeksy będą 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 przejrzysty sposób. Jednak jako klient interfejsu API musi tym zarządzać aplikacja. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest odpowiednie obrony i zapewnienie spójnego stanu dokumentu. Aby uzyskać spójność, zapoznaj się z sekcją WriteControl.

Ustalenie spójności stanów za pomocą funkcji WriteControl

Gdy odczytasz, a następnie zaktualizujesz dokument, możesz kontrolować sposób obsługi zmian konkurujących za pomocą pola WriteControl w metodzie documents.batchUpdate. WriteControl kontroluje 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. Utwórz prośby o aktualizację.
  3. Dodaj opcjonalny obiekt WriteControl z 1 z 2 opcji:
    1. Pole requiredRevisionId jest ustawione na revisionId dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od momentu przesłania żądania odczytu z 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 są stosowane względem zmian partnera. Wynik żądania zapisu uwzględnia zarówno zmiany żądania zapisu, jak i zmiany współpracownika w nowej wersji dokumentu. Serwer Dokumentów odpowiada za scalanie treści.

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