Dokument

W przewodniku omawiamy takie pojęcia jak główne metody, które składają się na Interfejs API Dokumentów Google, sposoby uzyskiwania dostępu do dokumentu oraz przepływ pracy podczas tworzenia dokument.

Metody interfejsu API

Zasób documents udostępnia metody, których używasz do wywoływania interfejsu Docs API. Poniższe metody umożliwiają tworzenie, odczytywanie i aktualizowanie dokumentów w Dokumentach:

Metody documents.get i documents.batchUpdate wymagają documentId jako parametr określający 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 metod odpowiedzi można znaleźć w sekcji Żądania i odpowiedzi.

Identyfikator dokumentu

documentId to unikalny identyfikator dokumentu, który można wyodrębnić z adresu URL dokumentu. Jest to konkretny ciąg znaków zawierający litery, cyfry i kilka znaków specjalnych. Identyfikatory dokumentów są stałe, nawet jeśli ich nazwa zmian.

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

Poniższe wyrażenie regularne umożliwia wyodrębnienie documentId z Adres URL Dokumentów Google:

/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 – naszym miejscu w chmurze posprzedażna. Chociaż interfejs Dokumentów API ma własne, niezależne metody, konieczne jest też używanie metod interfejsu Google Drive API do interakcji z pliki Dokumentów. Aby na przykład skopiować pliki Dokumentów, użyj Interfejs files.copy interfejsu Drive API . Więcej informacji znajdziesz w sekcji Kopiowanie istniejącego dokumentu.

Domyślnie podczas korzystania z interfejsu API Dokumentów nowy dokument jest zapisywany w w folderze głównym użytkownika na Dysku. Dostępne opcje zapisywania plików do folderu na Dysku. Więcej informacji znajdziesz w artykule Praca z: Foldery Dysku Google.

Praca z plikami Dokumentów

Aby odzyskać dokument z Mojego dysku użytkownika, często konieczne do pierwszego użycia files.list, aby pobrać Identyfikator pliku. Wywołanie metody bez parametrów zwraca listę wszystkich pliki i foldery użytkownika, włącznie z identyfikatorami.

Typ MIME dokumentu wskazuje typ i format danych. Format typu MIME w Dokumentach jest application/vnd.google-apps.document. Lista: Typy MIME: przeczytaj artykuł o obsługiwanych typach MIME w Google Workspace i na Dysku Google .

Aby wyszukać według typu MIME tylko pliki Dokumentów w folderze Mój Dysku, dołącz 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 .

Gdy już znasz documentId, użyj Metoda documents.get do pobrania jest to pełne wystąpienie określonego dokumentu. Więcej informacji: Prośby i odpowiedzi.

Aby wyeksportować bajty dokumentu Google Workspace, użyj files.export z parametrem documentId pliku do wyeksportowania i prawidłowe wyeksportowanie MIME . Więcej informacji znajdziesz w sekcji Eksportowanie Dokument Google Workspace treści.

Porównaj metody Get i List

W tej tabeli opisano różnice między Dyskiem Dokumentów i Dokumentów oraz dane zwracane w każdej z tych metod:

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 masz pewności, który plik musisz zmodyfikować, pobierz listę plików użytkownika.
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 ma istniejących treści, którymi trzeba się martwić, i nie ma żadnych współpracowników, którzy mogliby modyfikować stanu dokumentu. Ogólnie proces ten wygląda tak:

Proces tworzenia utwórz nowy dokument.
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ę Metoda documents.create włączona serwera WWW.
  2. Serwer WWW wysyła odpowiedź HTTP zawierającą instancję utworzono dokument jako zasób documents.
  3. Opcjonalnie aplikacja wywołuje metodę documents.batchUpdate. metoda atomowego wykonywania zestawu żądań edycji mających zapełnić dokument z 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ź.

Przepływ pracy związany z aktualizacją dokumentów

Aktualizowanie istniejącego dokumentu jest bardziej skomplikowane. Zanim zaczniesz tworzyć aktualizacji dokumentu, należy znać jego bieżący stan: jakie elementy jaka jest treść i kolejność elementów dokument. Jak to działa:

Przepływ pracy związany z aktualizacją dokument.
Rysunek 2. Przepływ pracy związany z aktualizowaniem dokumentu.

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

  1. Aplikacja wywołuje metodę Metoda documents.get w internecie serwerem, w którym jest documentId pliku do znalezienia.
  2. Serwer WWW wysyła odpowiedź HTTP zawierającą instancję określono dokument jako zasób documents. Zwrócony plik JSON zawiera zawartość, formatowanie i inne funkcje dokumentu.
  3. Aplikacja analizuje plik JSON, aby użytkownik mógł określić treść lub format .
  4. Aplikacja wywołuje metodę documents.batchUpdate, aby atomowo wykonać zestaw żądań edycji mających na celu zaktualizowanie dokumentu.
  5. Serwer WWW wysyła odpowiedź HTTP. Niektóre metody documents.batchUpdate przekazuje treść odpowiedzi informacje o zastosowanych żądaniach, w przypadku innych użytkowników pojawi się pusta odpowiedź.

Ten diagram nie uwzględnia przepływów pracy, w których równoczesne aktualizacje przez inne współpracowników w tym samym dokumencie. Aby dowiedzieć się więcej, zobacz najlepsze procedur. Planowanie współpracę.