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:
- Do utworzenia dokumentu użyj metody
documents.create
. - Aby pobrać zawartość określonego dokumentu, użyj metody
documents.get
. - Użyj metody
documents.batchUpdate
, aby atomowo przeprowadzić zbiór aktualizacji w określonym dokumencie.
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:
Na Rysunku 1 użytkownik korzystający z zasobu documents
ma następujący przepływ informacji:
- Aplikacja wywołuje metodę
documents.create
na serwerze WWW. - Serwer WWW wysyła odpowiedź HTTP, która zawiera wystąpienie utworzonego dokumentu jako zasób
documents
. - Opcjonalnie aplikacja wywołuje metodę
documents.batchUpdate
, aby atomowo wykonać zestaw żądań edycji w celu wypełnienia dokumentu danymi. - 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:
Na Rysunku 2 użytkownik korzystający z zasobu documents
ma następujący przepływ informacji:
- Aplikacja wywołuje metodę
documents.get
na serwerze internetowym, gdzie do znalezienia potrzebne jestdocumentId
pliku. - 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. - Aplikacja analizuje plik JSON, aby użytkownik mógł określić treść lub format do zaktualizowania.
- Aplikacja wywołuje metodę
documents.batchUpdate
, aby atomowo wykonać zestaw żądań edycji w celu zaktualizowania dokumentu. - 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.
Powiązane artykuły
- Struktura dokumentu Dokumentów Google
- Prośby i odpowiedzi
- Reguły i działanie zmian strukturalnych
- Sprawdzone metody uzyskiwania najlepszych wyników