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 następnych sekcjach omawiamy te zasady.

Edytowanie wstecz w celu zwiększenia wydajności

W ramach jednego wywołania metody documents.batchUpdate ułóż żądania w malejącym porządku według położenia indeksu. Dzięki temu nie trzeba obliczać zmian indeksu spowodowanych wstawianiem i usuwaniem elementów.

Planowanie współpracy

Stan dokumentu może się zmienić. 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ć tym 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.

Oto jak go używać:

  1. Pobierz dokument za pomocą metody documents.get i zapisz revisionId z zwróconego zasobu documents.
  2. Tworzenie próśb o aktualizację.
  3. Dodaj opcjonalny obiekt WriteControl, wybierając jedną z tych 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ą specjalnego przetwarzania w żądaniach 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, aby zastosować każdą z nich Requestdocuments.batchUpdatemetodą. 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 zastosowana karta Request do pierwszej karty w dokumencie. Szczegółowe informacje znajdziesz w dokumentacji Request.