Dokument

W tym przewodniku omawiamy podstawowe metody, które składają się na interfejs API Dokumentów Google, sposoby uzyskiwania dostępu do dokumentu oraz przepływ pracy podczas jego tworzenia.

Metody interfejsu API

Zasób documents udostępnia metody używane do wywoływania interfejsu API Dokumentów. Poniższe metody umożliwiają tworzenie, odczytywanie i aktualizowanie dokumentów w Dokumentach:

Metody documents.get i documents.batchUpdate wymagają documentId jako parametru określającego dokument docelowy. Metoda documents.create zwraca wystąpienie utworzonego dokumentu, z którego można odczytać documentId. Więcej informacji o żądaniach do interfejsu API Dokumentów i metodach odpowiedzi znajdziesz w artykule Żądania i odpowiedzi.

Identyfikator dokumentu

documentId to unikalny identyfikator dokumentu, który można pobrać z jego adresu URL. Jest to konkretny ciąg zawierający litery, cyfry i znaki specjalne. Identyfikatory dokumentów są stałe, nawet jeśli zmieni się ich nazwa.

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

Za pomocą tego wyrażenia regularnego można wyodrębnić documentId z adresu URL Dokumentów Google:

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

Jeśli znasz interfejs Google Drive API, documentId odpowiada wartości 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. Chociaż interfejs Dokumenty API ma własne samodzielne metody, często do interakcji z plikami Dokumentów użytkownika konieczne jest używanie metod API Dysku Google. Aby na przykład skopiować pliki Dokumentów, użyj metody files.copy interfejsu Drive API. Więcej informacji znajdziesz w sekcji Kopiowanie istniejącego dokumentu.

Podczas korzystania z interfejsu API Dokumentów nowy dokument jest domyślnie zapisywany w folderze głównym użytkownika na Dysku. Są też opcje zapisu pliku w folderze na Dysku. Więcej informacji znajdziesz w artykule Praca z folderami na Dysku Google.

Praca z plikami Dokumentów

Aby pobrać dokument z katalogu Mój dysk użytkownika, często trzeba najpierw użyć metody files.list Dysku w celu pobrania identyfikatora pliku. Wywołanie metody bez parametrów zwraca listę wszystkich plików i folderów użytkownika, w tym ich identyfikatorów.

Typ MIME dokumentu wskazuje typ i format danych. Format MIME w Dokumentach to application/vnd.google-apps.document. Listę typów MIME znajdziesz w artykule na temat obsługiwanych typów MIME w Google Workspace i Dysku Google.

Aby wyszukać według typu MIME pliki Dokumentów na Moim dysku, dołącz następujący filtr ciągu zapytania:

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

Więcej informacji o filtrach ciągów zapytań znajdziesz w artykule Wyszukiwanie plików i folderów.

Gdy znasz obiekt documentId, użyj metody documents.get, aby pobrać pełne wystąpienie określonego dokumentu. Więcej informacji znajdziesz w artykule Żądania i odpowiedzi.

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

Porównaj metody Get i List

W tabeli poniżej znajdziesz różnice między metodami Dysku i Dokumentów oraz dane, które są w nich zwracane:

Operator Opis Wykorzystanie
drive.files.get Pobiera metadane pliku według identyfikatora. Zwraca wystąpienie zasobu files. Uzyskiwanie metadanych konkretnego pliku
drive.files.list Pobiera pliki użytkownika. Zwraca listę plików. Gdy nie wiesz, który plik musisz zmodyfikować, wyświetl listę plików użytkowników.
docs.documents.get Pobiera najnowszą wersję określonego dokumentu, w tym całe formatowanie i tekst. Zwraca wystąpienie zasobu documents. Pobierz dokument dla konkretnego identyfikatora dokumentu.

Proces tworzenia dokumentu

Tworzenie i wypełnianie nowego dokumentu jest proste, ponieważ nie trzeba się martwić o istniejącą treść ani współpracowników, którzy mogliby zmieniać jego stan. Ogólnie wygląda to tak, jak na tym schemacie sekwencyjnym:

Przebieg procesu tworzenia i wypełniania nowego dokumentu.
Rysunek 1. Przepływ pracy tworzenia i wypełniania nowego dokumentu.

Na Rysunku 1 użytkownik korzystający z zasobu 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 wystąpienie utworzonego dokumentu jako zasób documents.
  3. Opcjonalnie aplikacja wywołuje metodę documents.batchUpdate, aby atomowo wykonać zestaw żądań edycji w celu wypełnienia dokumentu danymi.
  4. Serwer WWW wysyła odpowiedź HTTP. Niektóre metody documents.batchUpdate udostępniają treść odpowiedzi z informacjami o zastosowanych żądaniach, a inne wyświetlają pustą odpowiedź.

Przepływ pracy przy aktualizacji dokumentu

Aktualizowanie istniejącego dokumentu jest bardziej skomplikowane. Zanim zaczniesz wykonywać konkretne wywołania do aktualizacji dokumentu, musisz znać jego bieżący stan: jakie elementy się w nich składają, jaka jest ich zawartość i kolejność elementów w dokumencie. Jak to działa:

Proces aktualizowania dokumentu.
Rysunek 2. Proces aktualizowania dokumentu.

Na Rysunku 2 użytkownik korzystający z zasobu documents ma następujący przepływ informacji:

  1. Aplikacja wywołuje metodę documents.get na serwerze internetowym, gdzie do znalezienia potrzebne jest documentId pliku.
  2. Serwer WWW wysyła odpowiedź HTTP, która zawiera wystąpienie określonego dokumentu jako zasób documents. Zwracany plik JSON zawiera treść dokumentu, formatowanie i inne funkcje.
  3. Aplikacja analizuje plik JSON, aby użytkownik mógł określić treść lub format do zaktualizowania.
  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 metody documents.batchUpdate udostępniają treść odpowiedzi z informacjami o zastosowanych żądaniach, a inne wyświetlają pustą odpowiedź.

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