Dokument

W tym przewodniku omawiamy zagadnienia takie jak główne metody tworzące interfejs API Dokumentów Google, uzyskiwanie dostępu do dokumentu i przepływ pracy podczas tworzenia dokumentu.

Metody interfejsu API

Zasób documents zawiera metody używane do wywoływania interfejsu API Dokumentów. Poniższe metody pozwalają tworzyć, odczytywać i aktualizować dokumenty w Dokumentach:

Metody documents.get i documents.batchUpdate wymagają documentId jako parametru do określania dokumentu docelowego. Metoda documents.create zwraca wystąpienie utworzonego dokumentu, z którego można odczytać dokument 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. To konkretny ciąg znaków zawierający litery, cyfry i niektóre znaki specjalne. Identyfikatory dokumentów są stałe, nawet jeśli zmieni się ich nazwa.

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

Do wyodrębnienia documentId z adresu URL Dokumentów Google można użyć następującego wyrażenia regularnego:

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

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

Zarządzanie dokumentami na Dysku Google

Pliki Dokumentów są przechowywane na Dysku Google – usłudze przechowywania w chmurze. Chociaż interfejs Dokumentów API ma własne samodzielne metody, często do interakcji z plikami Dokumentów użytkowników konieczne jest również używanie metod interfejsu API Dysku Google. Na przykład do kopiowania plików Dokumentów użyj metody files.copy interfejsu Drive API. Więcej informacji znajdziesz w artykule 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ą opcje zapisywania 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 folderu Mój dysk 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 (w tym ich identyfikatorów) dla użytkownika.

Typ MIME dokumentu wskazuje typ i format danych. Format typu MIME dla Dokumentów to application/vnd.google-apps.document. Listę typów MIME znajdziesz w artykule Typy MIME obsługiwane przez Google Workspace i Dysk Google.

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

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

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

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

Aby wyeksportować zawartość bajtów dokumentu z Google Workspace, użyj metody files.export Dysku, podając documentId pliku do wyeksportowania i poprawny typ MIME do eksportu. Więcej informacji znajdziesz w artykule Eksportowanie treści dokumentów Google Workspace.

Porównaj metody Get i List

W poniższej tabeli opisano różnice między metodami Dysku i Dokumentów oraz danymi, które są zwracane:

Operator Opis Wykorzystanie
drive.files.get Pobiera metadane pliku według identyfikatora. Zwraca wystąpienie zasobu files. Pobieranie metadanych konkretnego pliku.
drive.files.list Pobiera pliki użytkownika. Zwraca listę plików. Jeśli nie wiesz, który plik musisz zmodyfikować, pobierz 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 określonego identyfikatora dokumentu.

Proces tworzenia dokumentu

Tworzenie i wypełnianie nowego dokumentu jest proste, ponieważ nie trzeba przejmować się żadnymi istniejącymi treściami i nie ma współpracowników, którzy mogliby zmieniać stan dokumentu. Zasadniczo działa to na tym schemacie:

Przepływ pracy związany z tworzeniem i wypełnianiem nowego dokumentu.
Rysunek 1. Proces tworzenia i wypełniania nowego dokumentu.

Na rys. 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 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 związany z aktualizacją dokumentów

Aktualizowanie istniejącego dokumentu jest bardziej skomplikowane. Zanim użyjesz znaczących wywołań w celu aktualizacji dokumentu, musisz znać jego bieżący stan: jakie elementy się na niego składają, jaka treść się w nich znajduje i kolejność elementów w dokumencie. Jak to działa:

i aktualizacji dokumentu.
Rysunek 2. Przepływ pracy związany z aktualizowaniem dokumentu.

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

  1. Aplikacja wywołuje metodę documents.get na serwerze WWW, udostępniając znaleziony plik documentId.
  2. Serwer WWW wysyła odpowiedź HTTP zawierającą wystąpienie określonego dokumentu jako zasobu documents. Zwrócony 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 osobno 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 są wprowadzane równocześnie aktualizacje przez innych współpracowników. Więcej informacji znajdziesz w sekcji ze sprawdzonymi metodami dotyczącymi planowania współpracy.