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: przesyła listę próśb o edytowanie, które mają być zastosowane do dokumentu w sposób niepodzielny, i zwraca listę wyników.
Metody documents.get i documents.batchUpdate wymagają parametru documentId, aby określić 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.
Pamiętaj, że nie możesz używać metody documents.get do pobierania opublikowanych dokumentów. Po opublikowaniu dokumenty publiczne mają inny format adresu URL. Próby użycia nowego documentId adresu URL z metodą documents.get zwracają kod stanu HTTP 404. Nie ma możliwości pobrania oryginalnego pliku documentId z opublikowanego adresu URL. Aby obejść ten problem, możesz użyć interfejsu Drive API do skopiowania opublikowanego dokumentu do dokumentu udostępnionego, a następnie uzyskać dostęp do tego pliku. Więcej informacji znajdziesz w artykule Publikowanie plików Dokumentów, Arkuszy, Prezentacji i Formularzy Google.
Aktualizacje zbiorcze
Metoda
documents.batchUpdate
przyjmuje listę obiektów
request, z których każdy określa pojedyncze żądanie do wykonania. Możesz na przykład sformatować akapit, a potem dodać 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 od siebie) 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.
Powiązane artykuły
- Struktura dokumentu w Dokumentach Google
- Reguły i działanie edytowania strukturalnego
- Żądania zbiorcze