Ten przewodnik przedstawia podstawowe metody żądania i odpowiedzi, które składają się na interfejs Google Docs API, oraz sposób aktualizowania dokumentu partiami.
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 reklam są do siebie zbliżone.
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 w Dokumentach Google.documents.get: zwraca pełną instancję wskazanego dokumentu. Możesz przeanalizować zwrócony obiekt 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 za pomocą 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 otrzymuje listę obiektów request, z których każdy określa jedno żą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 zgodnie z kolejnością, w jakiej występują w prośbie zbiorczej.
Wszystkie żądania w ramach aktualizacji zbiorczej są stosowane jako całość. 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, który zawiera listę obiektów response. Inne żądania nie muszą zwracać informacji i wyświetlają pustą odpowiedź. Obiekty na liście odpowiedzi zajmują tę samą pozycję indeksu co odpowiednie żądanie.
Popularny wzorzec przesyłania żądań zbiorczych:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Więcej informacji o tym, jak grupować wywołania interfejsu Docs API, znajdziesz w sprawdzonym sposobie wysyłania żądań zbiorczych. W documents.batchUpdate znajdziesz też dokumentację z informacjami o typach żą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