W tym przewodniku omawiamy główne metody żądań i odpowiedzi, które składają się na interfejs API Dokumentów Google, oraz sposoby aktualizowania dokumentu w partiach.
Interfejs API Dokumentów Google można wywołać przy użyciu żądania HTTP lub za pomocą metody w bibliotece klienta dla określonego języka. W większości przypadków są to równoważne.
Interfejs API Dokumentów Google zwraca odpowiedź HTTP, która zazwyczaj zawiera wynik wywołania żądania. Jeśli do wysyłania żądań używasz biblioteki klienta, odpowiedzi są zwracane w sposób zależny od języka.
Metody żądań
Interfejs API Dokumentów obsługuje następujące metody:
documents.create: utwórz pusty dokument w Dokumentach Google.documents.get: zwraca pełne wystąpienie określonego dokumentu. Możesz przeanalizować zwrócony plik JSON, aby wyodrębnić treść dokumentu, formatowanie i inne funkcje.documents.batchUpdate: umożliwia przesłanie listy próśb o zmianę, które mają zostać zastosowane do dokumentu w sposób atomowy, oraz zwracanie listy wyników.
Metody documents.get i documents.batchUpdate wymagają documentId jako parametru do określania dokumentu docelowego. Metoda documents.create zwraca wystąpienie utworzonego dokumentu, z którego można odczytać dokument documentId. Więcej informacji o documentId znajdziesz w artykule Identyfikator dokumentu.
Aktualizacje zbiorcze
Metoda documents.batchUpdate pobiera listę obiektów request, z których każdy określa jedno żądanie do wykonania. Na przykład sformatuj akapit, a potem dodaj obraz w treści. Przed zastosowaniem każde żądanie jest weryfikowane. Żądania są przetwarzane w kolejności, w jakiej występują w żądaniu zbiorczym.
Wszystkie żądania w aktualizacji zbiorczej są stosowane pojedynczo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja się nie powiedzie i nie zostaną zastosowane żadne (potencjalnie zależne) zmiany.
Niektóre metody documents.batchUpdate udostępniają odpowiedzi z informacjami o zastosowanych żądaniach. Te metody zwracają treść odpowiedzi, która zawiera listę obiektów response. W innych prośbach nie trzeba podawać informacji ani 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 tym, jak grupować wywołania interfejsu API Dokumentów Google, znajdziesz w artykule Sprawdzone metody dotyczące żądań zbiorczych oraz w dokumentacji referencyjnej documents.batchUpdate dotyczącej typów żądań i odpowiedzi.
Operacje aktualizacji zbiorczej
Istnieją różne typy zbiorczych żądań aktualizacji. Oto zestawienie typów żądań podzielonych na różne kategorie.