Dokument

W tym przewodniku znajdziesz informacje o podstawowych metodach interfejsu Google Docs API, sposobie uzyskiwania dostępu do dokumentu oraz przepływie 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. Interfejs Docs API ma własne samodzielne metody, ale często trzeba też używać metod interfejsu Google Drive API, aby wchodzić w interakcje z plikami Dokumentów użytkownika. 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 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 wartość 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 Google Workspace, użyj metody files.export Dysku z documentId pliku do wyeksportowania i poprawnym typem MIME eksportu. Więcej informacji znajdziesz w artykule Eksportowanie treści dokumentów Google Workspace.

Porównanie metod Get i List

W tabeli poniżej opisano różnice między metodami dotyczącymi Dysku 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 konkretnego pliku.
drive.files.list Pobiera pliki użytkownika. Zwraca listę plików. Jeśli nie masz pewności, który plik musisz zmodyfikować, pobierz listę plików użytkownika.
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

Utworzenie nowego dokumentu i wypełnienie go jest proste, ponieważ nie musisz się martwić o istniejące treści i nie ma współpracowników, którzy mogliby zmienić stan dokumentu. Ogólnie wygląda to tak:

Przepływ pracy służący do tworzenia i wypełniania 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 wykonać automatycznie 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 zastosowanej prośbie, a inne zwracają 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ą instancję określonego dokumentu jako zasób documents. Zwracany obiekt JSON zawiera treść dokumentu, formatowanie i inne funkcje.
  3. Aplikacja analizuje dane w formacie JSON, aby użytkownik mógł określić, jakie treści lub format ma zaktualizować.
  4. Aplikacja wywołuje metodę documents.batchUpdate, aby wykonać zestaw żądań edycji w ramach jednej operacji 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 sprawdzonych metod Planowanie współpracy.