Dokument

Z tego przewodnika dowiesz się więcej o takich kwestiach jak podstawowe metody interfejsu Google Docs API, dostęp do dokumentu i przepływ pracy podczas tworzenia dokumentu.

Metody interfejsu API

Zasób documents udostępnia metody, których możesz używać do wywoływania interfejsu Docs API. Te metody umożliwiają tworzenie, odczytywanie i aktualizowanie dokumentów Dokumentów:

• Aby utworzyć dokument, użyj documents.create metody.
• Aby pobrać zawartość określonego dokumentu, użyj metody documents.get.
• Aby atomowo wykonać zestaw aktualizacji w określonym dokumencie, użyj documents.batchUpdate metody.

Metody documents.get i documents.batchUpdate wymagają parametru documentId, który określa dokument docelowy. Metoda documents.create zwraca instancję utworzonego dokumentu, z którego 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 adresu URL dokumentu. Jest to konkretny ciąg znaków zawierający litery, cyfry i niektóre znaki specjalne. Identyfikatory dokumentów są stałe, nawet jeśli nazwa dokumentu się zmieni.

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

Do wyodrębnienia documentId z adresu URL Dokumentów Google można użyć tego 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, czyli w naszej usłudze przechowywania w chmurze. Interfejs Docs API ma własne metody, ale często trzeba też używać metod interfejsu Google Drive API, aby wchodzić w interakcje 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 na Dysku Google.

Praca z plikami Dokumentów

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

Typ MIME dokumentu wskazuje typ i format danych. Format typu MIME w Dokumentach 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 ciągu zapytania znajdziesz w artykule Wyszukiwanie plików i folderów.

Gdy znasz 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ść bajtową dokumentu Google Workspace, 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ównanie metod Get i List

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

Przepływ pracy podczas tworzenia dokumentu

Tworzenie i wypełnianie nowego dokumentu jest proste, ponieważ nie ma istniejącej treści, o którą trzeba się martwić, ani współpracowników, którzy mogliby zmienić stan dokumentu. Koncepcyjnie działa to tak, jak pokazano na tym diagramie sekwencji:

Na rysunku 1 użytkownik wchodzący w interakcje 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 zwracają pustą odpowiedź.

Przepływ pracy podczas aktualizowania dokumentu

Aktualizowanie istniejącego dokumentu jest bardziej złożone. Zanim będzie można wykonywać znaczące wywołania w celu zaktualizowania dokumentu, musisz znać jego bieżący stan: jakie elementy go tworzą, jaka jest zawartość tych elementów i jaka jest kolejność elementów w dokumencie. Ten diagram sekwencji pokazuje, jak to działa:

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

1. Aplikacja wywołuje metodę documents.get na serwerze WWW 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 kod JSON zawiera treść dokumentu, formatowanie i inne funkcje.
3. Aplikacja analizuje kod JSON, aby użytkownik mógł określić, które treści lub formaty mają zostać zaktualizowane.
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 zwracają pustą odpowiedź.

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

Powiązane artykuły

• Struktura dokumentu Dokumentów Google
• Żądania i odpowiedzi
• Reguły i zachowania dotyczące edycji strukturalnych
• Sprawdzone metody zapewniające najlepsze wyniki