Dokument

W tym przewodniku znajdziesz informacje o podstawowych metodach, które składają się na Google Docs API, o tym, jak uzyskać dostęp do dokumentu, oraz o procesie tworzenia dokumentu.

Metody interfejsu API

Zasób documents udostępnia metody, których możesz używać do wywoływania interfejsu Docs API. Dokumenty Google możesz tworzyć, odczytywać i aktualizować za pomocą tych metod:

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 żądaniach i metodach odpowiedzi interfejsu Docs API znajdziesz w artykule Żądania i odpowiedzi.

Identyfikator dokumentu

documentId to unikalny identyfikator dokumentu, który można uzyskać z jego adresu URL. Jest to ciąg znaków zawierający litery, cyfry i niektóre znaki specjalne. Identyfikatory dokumentów są stałe, nawet jeśli nazwa dokumentu ulegnie zmianie.

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

Aby wyodrębnić documentId z adresu URL Dokumentów Google, możesz użyć tego wyrażenia regularnego:

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

Jeśli znasz interfejs Google Drive API, znak documentId odpowiada znakowi id w zasobie files.

Zarządzanie dokumentami na Dysku Google

Pliki Dokumentów są przechowywane na Dysku Google, naszej usłudze przechowywania danych w chmurze. Interfejs Docs API ma własne metody, ale często konieczne jest też używanie metod interfejsu Google Drive API do interakcji z plikami Dokumentów użytkownika. Aby na przykład skopiować pliki Dokumentów, użyj metody files.copy interfejsu Drive API. Więcej informacji znajdziesz w artykule Kopiowanie istniejącego dokumentu.

Domyślnie podczas korzystania z interfejsu Docs API nowy dokument jest zapisywany w folderze głównym użytkownika na Dysku. Istnieją opcje zapisywania pliku w folderze na Dysku. Więcej informacji znajdziesz w artykule Praca z folderami Dysku Google.

Praca z plikami Dokumentów

Aby pobrać dokument z Moich plików użytkownika, często trzeba najpierw użyć metody files.list Dysku, aby pobrać identyfikator pliku. Wywołanie tej metody bez parametrów zwraca listę wszystkich plików i folderów użytkownika, w tym ich identyfikatory.

Typ MIME dokumentu określa typ i format danych. Format typu MIME w przypadku Dokumentów to application/vnd.google-apps.document. Listę typów MIME znajdziesz w artykule Obsługiwane typy MIME w Google Workspace i na Dysku Google.

Aby wyszukać tylko pliki Dokumentów na Moim Dysku według typu MIME, dodaj ten filtr ciągu zapytania:

q: mimeType = 'application/vnd.google-apps.document'

Więcej informacji o filtrach w postaci ciągu zapytania znajdziesz w artykule Wyszukiwanie plików i folderów.

Gdy poznasz documentId, użyj metody documents.get, aby pobrać pełną instancję określonego dokumentu. Więcej informacji znajdziesz w sekcji Żądania i odpowiedzi.

Aby wyeksportować zawartość bajtową dokumentu Google Workspace, użyj metody files.export Dysku z documentId pliku do wyeksportowania i odpowiednim typem MIME eksportu. Więcej informacji znajdziesz w artykule Eksportowanie treści dokumentu Google Workspace.

Porównanie metod Get i List

W tabeli poniżej opisano różnice między metodami Drive i Dokumentów oraz dane zwracane przez każdą z nich:

Operator Opis Wykorzystanie
drive.files.get Pobiera metadane pliku według identyfikatora. Zwraca instancję zasobu files. Pobierz metadane określonego pliku.
drive.files.list Pobiera pliki użytkownika. Zwraca listę plików. Uzyskaj listę plików użytkownika, gdy nie masz pewności, który plik musisz zmodyfikować.
docs.documents.get Pobiera najnowszą wersję określonego dokumentu, w tym całe formatowanie i tekst. Zwraca instancję zasobu documents. Pobieranie dokumentu na podstawie identyfikatora.

Przepływ pracy związany z tworzeniem dokumentów

Tworzenie i wypełnianie nowego dokumentu jest proste, ponieważ nie ma istniejących treści, o które trzeba się martwić, ani współpracowników, którzy mogliby zmienić stan dokumentu. Koncepcja działania tej funkcji jest przedstawiona na tym diagramie sekwencji:

Przepływ pracy umożliwiający tworzenie i wypełnianie nowego dokumentu.
Rysunek 1. Przepływ pracy związany z tworzeniem i wypełnianiem nowego dokumentu.

Na ilustracji 1 użytkownik wchodzący w interakcję z zasobem documents ma następujący przepływ informacji:

  1. Aplikacja wywołuje metodę documents.create na serwerze WWW.
  2. Serwer WWW wysyła odpowiedź HTTP, która zawiera instancję utworzonego dokumentu jako zasób documents.
  3. Opcjonalnie aplikacja może wywołać metodę documents.batchUpdate, aby atomowo wykonać zestaw żądań edycji i wypełnić dokument danymi.
  4. Serwer WWW wysyła odpowiedź HTTP. Niektóre documents.batchUpdate metody zwracają treść odpowiedzi z informacjami o zastosowanych żądaniach, a inne – pustą odpowiedź.

Przepływ pracy związany z aktualizacją dokumentu

Aktualizowanie istniejącego dokumentu jest bardziej skomplikowane. Zanim zaczniesz wykonywać przydatne wywołania w celu zaktualizowania dokumentu, musisz znać jego bieżący stan: jakie elementy go tworzą, jaka jest zawartość tych elementów i w jakiej kolejności występują one w dokumencie. Ten diagram sekwencji pokazuje, jak to działa:

Przepływ pracy umożliwiający aktualizację dokumentu.
Rysunek 2. Przepływ pracy umożliwiający aktualizację dokumentu.

Na ilustracji 2 użytkownik wchodzący w interakcję z zasobem documents ma następujący przepływ informacji:

  1. Aplikacja wywołuje na serwerze internetowym metodę documents.get z documentId pliku do znalezienia.
  2. Serwer WWW wysyła odpowiedź HTTP, która zawiera instancję określonego dokumentu jako zasób documents. Zwrócony plik JSON zawiera treść dokumentu, formatowanie i inne funkcje.
  3. Aplikacja analizuje plik JSON, aby użytkownik mógł określić, które treści lub formaty należy zaktualizować.
  4. Aplikacja wywołuje metodę documents.batchUpdate, aby atomowo wykonać zestaw żądań edycji w celu zaktualizowania dokumentu.
  5. Serwer WWW wysyła odpowiedź HTTP. Niektóre documents.batchUpdate metody zwracają treść odpowiedzi z informacjami o zastosowanych żądaniach, a inne – pustą odpowiedź.

Ten diagram nie uwzględnia przepływów pracy, w których inni współpracownicy wprowadzają równoczesne zmiany w tym samym dokumencie. Więcej informacji znajdziesz w sekcji sprawdzonych metod Planowanie współpracy.