Ten przewodnik przedstawia główne metody żądań i odpowiedzi, które składają się na Google Docs API, oraz wyjaśnia, jak aktualizować dokument w partiach.
Interfejs Google Docs API możesz wywołać za pomocą żądania HTTP lub wywołania metody w bibliotece klienta w konkretnym języku. Są one w dużej mierze równoważne.
Interfejs Google Docs API zwraca odpowiedź HTTP, która zwykle zawiera wynik wywołania żądania. Gdy do wysyłania żądań używasz biblioteki klienta, odpowiedzi są zwracane w sposób charakterystyczny dla danego języka.
Metody żądania
Interfejs Docs API obsługuje te metody:
documents.create: Utwórz pusty dokument Google.documents.get: zwraca pełną instancję określonego dokumentu. Możesz przeanalizować zwrócony plik JSON, aby wyodrębnić zawartość dokumentu, formatowanie i inne funkcje.documents.batchUpdate: Prześlij listę próśb o edytowanie, aby zastosować je do dokumentu w sposób atomowy, i zwróć listę wyników.
Metody documents.get i documents.batchUpdate wymagają parametru documentId, który określa dokument docelowy. Metoda documents.create zwraca instancję utworzonego dokumentu, z której możesz odczytać documentId. Więcej informacji o documentId znajdziesz w artykule Identyfikator dokumentu.
Opublikowane dokumenty
Nie możesz używać metody documents.get do pobierania opublikowanych dokumentów. Po opublikowaniu dokumenty publiczne mają inny format adresu URL z odrębnym, publicznymdocumentId. Próby użycia publicznego interfejsu documentId z metodą documents.get zwracają kod stanu HTTP 404.
Podobnie nie możesz użyć metody interfejsu Drive API
files.copy do skopiowania opublikowanego dokumentu.
Aby pobrać lub skopiować opublikowany dokument, musisz użyć oryginalnegodocumentId. Nie ma metod wyodrębniania pierwotnego parametru documentId z opublikowanego adresu URL.
Aby dowiedzieć się więcej, zobacz:
- Publikowanie plików Dokumentów, Arkuszy, Prezentacji i Formularzy Google
- Kopiowanie istniejącego dokumentu
Aktualizacje zbiorcze
Metoda
documents.batchUpdate
przyjmuje listę obiektów
request, z których każdy określa pojedyncze żądanie do wykonania. Na przykład sformatuj akapit, a potem dodaj obraz w tekście. Każda prośba jest weryfikowana przed zastosowaniem, a prośby są przetwarzane w kolejności, w jakiej pojawiają się w żądaniu zbiorczym.
Wszystkie żądania w aktualizacji zbiorczej są stosowane niepodzielnie. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja się nie powiedzie i żadne zmiany (potencjalnie zależne) nie zostaną zastosowane.
Niektóre metody documents.batchUpdate zwracają odpowiedzi zawierające informacje o zastosowanych żądaniach. Te metody zwracają treść odpowiedzi zawierającą listę obiektów response.
Inne żądania nie muszą zwracać informacji i mogą generować pustą odpowiedź. Obiekty na liście odpowiedzi mają taką samą kolejność indeksów jak odpowiednie żądania.
Popularny wzorzec tworzenia żądań zbiorczych wygląda tak:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Pełne informacje o tym, jak grupować wywołania interfejsu API Dokumentów, oraz dokumentację referencyjną typów żądań i odpowiedzi znajdziesz w sprawdzonych metodach dotyczących żądań zbiorczych.documents.batchUpdate
Operacje aktualizacji zbiorczej
Istnieją różne typy żądań aktualizacji zbiorczych. Oto podział rodzajów próśb na różne kategorie.