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:
- Aby utworzyć dokument, użyj metody
documents.create
. - Użyj metody
documents.get
, aby pobrać zawartość określonego dokumentu. - Użyj metody
documents.batchUpdate
, aby osobno przeprowadzić zbiór aktualizacji określonego dokumentu.
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:
Na rys. 1 użytkownik wchodzący w interakcję z zasobem 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 instancję 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 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:
Na Rysunku 2 użytkownik wchodzący w interakcję z zasobem documents
ma następujący przepływ informacji:
- Aplikacja wywołuje metodę
documents.get
na serwerze WWW, udostępniając znaleziony plikdocumentId
. - 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. - Aplikacja analizuje plik JSON, aby użytkownik mógł określić treść lub format do zaktualizowania.
- Aplikacja wywołuje metodę
documents.batchUpdate
, aby osobno 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 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.
Powiązane artykuły
- Struktura dokumentu w Dokumentach Google
- Prośby i odpowiedzi
- Reguły i działanie edytowania struktury
- Sprawdzone metody uzyskiwania najlepszych wyników