Wprowadzenie

Interfejs API Dokumentów Google umożliwia tworzenie i modyfikowanie dokumentów.

Aplikacje można zintegrować z interfejsem Docs API, aby tworzyć dopracowane dokumenty na podstawie danych przekazywanych zarówno przez użytkowników, jak i przez system. Dzięki interfejsowi API możesz:

  • Automatyzacja procesów
  • Zbiorcze tworzenie dokumentacji
  • generowanie faktur i umów;

Omówienie interfejsu API

Zasób documents zawiera metody używane do wywoływania interfejsu Docs API.

Metody interfejsu API

Poniższe metody umożliwiają tworzenie, odczytywanie i aktualizowanie dokumentów w Dokumentach Google:

Metody get i batchUpdate wymagają parametru documentId (patrz poniżej) do określenia dokumentu docelowego. Metoda create zwraca wystąpienie utworzonego dokumentu, z którego można odczytać identyfikator.

Aktualizacje zbiorcze

Metoda batchUpdate pobiera listę obiektów żądania i wprowadza aktualizacje zgodnie z kolejnością, w jakiej występują w żądaniu zbiorczym. Aktualizacje w ramach aktualizacji zbiorczej są stosowane atomowo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, nie następuje cała aktualizacja, a żadne (potencjalnie zależne) zmiany nie są wprowadzane.

Metoda batchUpdate zwraca listę obiektów odpowiedzi. Obiekty na tej liście zajmują tę samą kolejność indeksowania co odpowiednie żądanie.

Aby dowiedzieć się, jak grupować wywołania interfejsu API, zapoznaj się ze sprawdzonymi metodami dotyczącymi żądań zbiorczych oraz zapoznaj się z dokumentacją batchUpdate dotyczącą typów żądań i odpowiedzi.

Identyfikator dokumentu

Identyfikatory dokumentów odnoszą się do dokumentu i mogą pochodzić z adresu URL:

https://docs.google.com/document/d/documentId/edit

documentId to unikalny ciąg znaków zawierający litery, cyfry i niektóre znaki specjalne. Aby wyodrębnić identyfikator dokumentu z adresu URL Dokumentów Google, użyj poniższego wyrażenia regularnego:

/document/d/([a-zA-Z0-9-_]+)

Jeśli znasz interfejs Google Drive API, documentId odpowiada identyfikatorowi zasobu File.

Lokalizacje w dokumencie: indeksy

Gdy aktualizujesz treść dokumentu, każda aktualizacja odbywa się w jednym miejscu lub w określonym zakresie w obrębie dokumentu. Te lokalizacje i zakresy są określane za pomocą indeksów, które reprezentują przesunięcie w obrębie segmentu dokumentu. Aby dowiedzieć się więcej o indeksach i korzystaniu z nich, przeczytaj przewodnik po koncepcji Struktura dokumentu w Dokumentach Google.

Proces aktualizowania dokumentu

Tworzenie i wypełnianie nowego dokumentu jest proste, ponieważ nie trzeba się martwić o istniejącą zawartość i nie ma współpracowników, którzy mogliby zmieniać stan dokumentu. Ogólnie przebiega to w taki sposób, jak pokazano na tym diagramie:

Proces tworzenia i wypełniania nowego dokumentu.

Aktualizowanie istniejącego dokumentu jest bardziej złożone. Zanim zaczniesz wykonywać znaczące wywołania do aktualizacji dokumentu, musisz poznać jego bieżący stan: jakie elementy składają się na poszczególne elementy, jaka jest ich zawartość i gdzie znajdują się wszystkie te elementy w dokumencie. Ten diagram pokazuje, jak to działa:

Proces aktualizowania dokumentu.

Ten diagram nie uwzględnia przepływów pracy, w których równoczesne aktualizacje są wprowadzane przez innych współpracowników w tym samym dokumencie. Więcej informacji na ten temat znajdziesz w artykule Planowanie współpracy.