Dokument

W tym przewodniku omawiamy takie zagadnienia jak podstawowe metody interfejsu Google Docs API, sposób uzyskiwania dostępu do dokumentu oraz przepływ pracy podczas tworzenia dokumentu.

Metody interfejsu API

Zasób documents udostępnia metody, których używasz do wywoływania interfejsu Docs API. Za pomocą tych metod możesz tworzyć, czytać i aktualizować dokumenty w Dokumentach:

Metody documents.get i documents.batchUpdate wymagają parametru documentId, aby określić dokument docelowy. Metoda documents.create zwraca instancję utworzonego dokumentu, z którego możesz odczytać wartość 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 adresu URL dokumentu. Jest to określony ciąg znaków zawierający litery, cyfry i niektóre znaki specjalne. Identyfikatory dokumentów są stabilne, 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 API Dysku Google, documentId odpowiada id w zasobach files.

Zarządzanie dokumentami na Dysku Google

Pliki Dokumentów są przechowywane na Dysku Google, naszej usłudze przechowywania danych 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 Google Drive API. Na przykład, aby skopiować pliki Dokumentów, użyj metody files.copy interfejsu Drive API. Więcej informacji znajdziesz w artykule Kopiowanie istniejącego dokumentu.

Domyślnie, gdy używasz interfejsu Docs API, nowy dokument jest zapisywany w folderze głównym użytkownika na Dysku. Plik można zapisać w folderze Dysku na kilka sposobów. Więcej informacji znajdziesz w artykule Praca z folderami na Dysku Google.

Praca z plikami Dokumentów

Aby pobrać dokument z Mojego dysku użytkownika, często trzeba najpierw użyć metody files.list Dysku, aby pobrać identyfikator 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 typu MIME dla Dokumentów to application/vnd.google-apps.document. Listę obsługiwanych typów MIME znajdziesz w artykule Obsługiwane typy MIME w Google Workspace i na Dysku Google.

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

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

Więcej informacji o filtrach w 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 dokumentu Google Workspace.

Porównanie metod 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 instancję zasobu files. Pobierz metadane konkretnego pliku.
drive.files.list Pobiera pliki użytkownika. Zwraca listę plików. Jeśli nie wiesz, który plik należy zmodyfikować, pobierz listę plików użytkowników.
docs.documents.get Pobiera najnowszą wersję wskazanego dokumentu, w tym formatowanie i tekst. Zwraca instancję zasobu documents. Pobierz dokument o określonym identyfikatorze.

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 rysunku 1. użytkownik, który wchodzi w interakcję z zasobami 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 zawierającą 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ź.

Proces aktualizacji dokumentu

Aktualizowanie istniejącego dokumentu jest bardziej skomplikowane. Zanim wykonasz istotne wywołania dotyczące aktualizacji dokumentu, musisz znać jego bieżący stan: jakie elementy go tworzą, jakie treści zawierają te elementy i jaką jest ich kolejność w dokumencie. Na poniższym diagramie sekwencji pokazano, jak to działa:

Przepływ pracy służący do aktualizowania dokumentu.
Rysunek 2. Przepływ pracy służący do aktualizowania dokumentu.

Na rysunku 2. użytkownik, który wchodzi w interakcję z zasobami documents, ma następujący przepływ informacji:

  1. Aplikacja wywołuje metodę documents.get na serwerze internetowym, podając documentId pliku, który ma zostać znaleziony.
  2. Serwer WWW wysyła odpowiedź HTTP zawierającą wystąpienie określonego dokumentu jako zasobu documents. Zwracany obiekt 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 zastosowanej prośbie, a inne zwracają pustą odpowiedź.

Ten diagram nie uwzględnia procesów, w których w tym samym dokumencie są wprowadzane równoległe zmiany przez innych współpracowników. Więcej informacji znajdziesz w sekcji ze sprawdzonymi metodami dotyczącymi planowania współpracy.