Z tego przewodnika dowiesz się, jakie są podstawowe metody żądań i odpowiedzi w interfejsie Google Docs API oraz jak zbiorczo aktualizować dokument.
Interfejs Google Docs API możesz wywołać za pomocą żądania HTTP lub przez wywołanie 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: tworzy pusty dokument Google.documents.get: zwraca pełną instancję określonego dokumentu. Możesz przeanalizować zwrócony kod JSON, aby wyodrębnić treść dokumentu, formatowanie i inne funkcje.documents.batchUpdate: przesyła listę żądań edycji, które mają być stosowane atomowo do dokumentu, 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.
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, publicznym identyfikatorem documentId. Próby użycia publicznego identyfikatora 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ć oryginalnego identyfikatora documentId. Nie ma metod, które umożliwiają wyodrębnienie oryginalnego identyfikatora documentId z opublikowanego adresu URL.
Więcej informacji znajdziesz w tych artykułach:
- 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. Możesz na przykład sformatować akapit, a następnie dodać obraz w tekście. Każde żądanie jest weryfikowane przed zastosowaniem, a żądania są przetwarzane w kolejności, w jakiej występują w żądaniu zbiorczym.
Wszystkie żądania w aktualizacji zbiorczej są stosowane atomowo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja nie powiedzie się i żadne (potencjalnie zależne) zmiany nie zostaną zastosowane.
Niektóre metody documents.batchUpdate zwracają odpowiedzi z informacjami o zastosowanych żądaniach. Te metody zwracają response
body
która zawiera listę
response obiektów.
Inne żądania nie muszą zwracać informacji i wyświetlają pustą odpowiedź. Obiekty na liście odpowiedzi mają tę samą kolejność indeksów co odpowiadające im żądania.
Popularny wzorzec wysyłania żądań zbiorczych wygląda tak:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Szczegółowe informacje o tym, jak zbiorczo wywoływać interfejs Docs API, orazdocuments.batchUpdate dokumentację referencyjną z typami żądań i odpowiedzi znajdziesz w artykule Sprawdzone metody dotyczące żądań zbiorczych.
Operacje aktualizacji zbiorczej
Istnieją różne typy żądań aktualizacji zbiorczej. Oto zestawienie typów żądań pogrupowanych w różne kategorie.