Ten przewodnik przedstawia podstawowe metody żądania i odpowiedzi, które składają się na interfejs Google Docs API, oraz wyjaśnia, jak zaktualizować dokument zbiorczo.
Interfejs API Dokumentów Google możesz wywołać za pomocą żądania HTTP lub metody wywołania w bibliotece klienta w danym języku. Te dwa rodzaje dopasowania są w dużej mierze równoważne.
Interfejs Google Docs API zwraca odpowiedź HTTP, która zwykle zawiera wynik wywołania żądania. Gdy używasz biblioteki klienta do wysyłania żądań, odpowiedzi są zwracane w sposób zależny od języka.
Metody żądania
Interfejs Docs API obsługuje te metody:
documents.create: utwórz pusty dokument Dokumentów Google.documents.get: zwraca pełny egzemplarz wskazanego 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 edycję, które mają być stosowane do dokumentu w sposób atomowy, i zwracaj listę wyników.
Metody documents.get i documents.batchUpdate wymagają parametru documentId, który służy do określenia dokumentu docelowego. Metoda documents.create zwraca instancję utworzonego dokumentu, z którego możesz odczytać wartość documentId. Więcej informacji o documentId znajdziesz w sekcji Identyfikator dokumentu.
Pamiętaj, że nie możesz używać metody documents.get do pobierania opublikowanych dokumentów. Po opublikowaniu dokumenty publiczne używają innego formatu adresu URL. Próby użycia nowego parametru documentId adresu URL w ramach metody documents.get zwracają kod stanu HTTP 404. Nie ma sposobu na pobranie pierwotnego adresu URL documentId z opublikowanego adresu URL. Aby obejść ten problem, możesz użyć interfejsu Drive API, aby skopiować opublikowany dokument do udostępnionego dokumentu, 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. Na przykład możesz sformatować akapit, a następnie dodać obraz w tekście. Każda prośba jest weryfikowana przed zastosowaniem, a prośby są przetwarzane w kolejności, w jakiej występują w prośbie zbiorczej.
Wszystkie żądania w ramach aktualizacji zbiorczej są stosowane w sposób atomowy. Oznacza to, że jeśli żądanie nie jest prawidłowe, cała aktualizacja kończy się niepowodzeniem i żadne z (potencjalnie zależnych) zmian nie zostaną zastosowane.
Niektóre metody documents.batchUpdate zwracają odpowiedzi z informacjami o zastosowanej prośbie. Te metody zwracają element odpowiedzi zawierający listę obiektów response.
Inne żądania nie muszą zwracać informacji i wyświetlać pustej odpowiedzi. Obiekty na liście odpowiedzi zajmują tę samą pozycję indeksu co odpowiadające im żądania.
Popularny wzorzec przesyłania żądań zbiorczych:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Zapoznaj się ze sprawdzonymi metodami dotyczącymi żądań zbiorczych, aby dowiedzieć się więcej o wykonywaniu zbiorczych wywołań interfejsu API Dokumentów. W documents.batchUpdate znajdziesz też dokumentację na temat typów żądań i odpowiedzi.
Operacje zbiorczej aktualizacji
Istnieją różne typy próśb o aktualizację zbiorczą. Oto podział typów żądań na różne kategorie.
Powiązane artykuły
- Struktura dokumentu w Dokumentach Google
- Reguły i zachowanie dotyczące edycji struktury
- Żądania zbiorcze