Ten przewodnik przedstawia główne metody żądań i odpowiedzi, które składają się na interfejs Google Docs API, oraz sposób aktualizowania dokumentu 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, które mają być zastosowane do dokumentu w sposób niepodzielny, 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 używają innego formatu 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 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 następnie 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 nie powiedzie się 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)
Szczegółowe informacje o tym, jak grupować wywołania interfejsu API Dokumentów, oraz dokumentację referencyjną dotyczącą 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 żądań na różne kategorie.