W tym przewodniku przedstawiamy podstawowe metody żądań i odpowiedzi, które składają się na interfejs API Dokumentów Google, oraz sposób aktualizowania dokumentu partiami.
Interfejs API Dokumentów Google możesz wywołać przy użyciu żądania HTTP lub metody w bibliotece klienta w konkretnym języku. Są to w większym stopniu równoważne.
Interfejs API Dokumentów Google zwraca odpowiedź HTTP, która zazwyczaj zawiera wynik wywołania żądania. Jeśli do przesyłania żądań używana jest biblioteka klienta, odpowiedzi są zwracane w sposób specyficzny dla danego języka.
Metody wysyłania żądań
Interfejs API Dokumentów obsługuje następujące metody:
documents.create: utwórz pusty dokument Dokumentów Google.documents.get: zwraca pełną instancję określonego dokumentu. Możesz przeanalizować zwrócony kod JSON, aby wyodrębnić zawartość dokumentu, formatowanie i inne funkcje.documents.batchUpdate: przesyła listę próśb o zmianę, które zostaną zastosowane atomowo w dokumencie, i zwraca listę wyników.
Metody documents.get i documents.batchUpdate wymagają documentId jako parametru określającego dokument docelowy. Metoda documents.create zwraca wystąpienie utworzonego dokumentu, z którego można odczytać documentId. Więcej informacji na temat documentId znajdziesz w sekcji Identyfikator dokumentu.
Aktualizacje zbiorcze
Metoda documents.batchUpdate przyjmuje listę obiektów request, z których każdy określa jedno żądanie do wykonania. Na przykład sformatuj akapit, a następnie dodaj obraz w tekście. Przed zastosowaniem każde żądanie jest weryfikowane. Żądania są przetwarzane zgodnie z kolejnością, w jakiej występują w żądaniu zbiorczym.
Wszystkie żądania w ramach aktualizacji zbiorczej są stosowane atomowo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja kończy się niepowodzeniem i nie są stosowane żadne (potencjalnie zależne) zmiany.
Niektóre metody documents.batchUpdate dostarczają odpowiedzi z informacjami o zastosowanych żądaniach. Metody te zwracają treść odpowiedzi, która zawiera listę obiektów response. Inne żądania nie muszą zwracać informacji i wyświetlać pustej odpowiedzi. Obiekty na liście odpowiedzi zajmują tę samą kolejność indeksu co odpowiednie żądanie.
Popularny wzorzec tworzenia żądań zbiorczych wygląda tak:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Szczegółowe informacje o grupowaniu wywołań interfejsu API Dokumentów znajdziesz w sprawdzonych metodach dotyczących żądań zbiorczych, a także w dokumentacji referencyjnej typów żądań i odpowiedzi documents.batchUpdate.
Operacje aktualizacji zbiorczej
Istnieją różne typy żądań aktualizacji zbiorczych. Oto zestawienie typów żądań podzielonych na różne kategorie.