本指南將介紹各種概念,例如組成 Google Document API 的主要方法、如何存取文件,以及建立文件的工作流程。
API 方法
documents
資源提供叫用 Document API 的方法。下列方法可讓您建立、讀取及更新文件文件:
- 請使用
documents.create
方法建立文件。 - 使用
documents.get
方法擷取指定文件的內容。 - 使用
documents.batchUpdate
方法,可對指定文件以不可分割的形式執行一組更新。
documents.get
和 documents.batchUpdate
方法需要 documentId
做為參數來指定目標文件。documents.create
方法會傳回所建立文件的執行個體,您可以在其中讀取 documentId
。如要進一步瞭解 Document API 要求和回應方法,請參閱要求和回應。
文件 ID
documentId
是文件的專屬 ID,可從文件的網址取得。這是特定字串,包含字母、數字和某些特殊字元。即使文件名稱有所變更,文件 ID 仍會保持穩定。
https://docs.google.com/document/d/DOCUMENT_ID/edit
下列規則運算式可用來從 Google 文件網址擷取 documentId
:
/document/d/([a-zA-Z0-9-_]+)
如果您熟悉 Google Drive API,documentId
則對應至 files
資源中的 id
。
管理 Google 雲端硬碟中的文件
文件檔案會儲存在 Google 雲端硬碟的雲端式儲存空間服務。雖然 Document API 有自己的獨立方法,但通常需要使用 Google Drive API 方法與使用者的文件檔案互動。舉例來說,如要複製文件檔案,請使用 Drive API 的 files.copy
方法。詳情請參閱「複製現有文件」。
根據預設,使用 Document API 時,新文件會儲存至使用者的雲端硬碟根資料夾。系統提供將檔案儲存至 雲端硬碟資料夾的選項。詳情請參閱「使用 Google 雲端硬碟資料夾」。
使用文件檔案
如要從使用者的「我的雲端硬碟」擷取文件,您通常需要先使用雲端硬碟的 files.list
方法擷取檔案的 ID。若呼叫不含任何參數的方法,系統會傳回使用者的所有檔案和資料夾清單,包括 ID 在內。
文件的 MIME 類型會指出資料類型和格式。文件的 MIME 類型格式為 application/vnd.google-apps.document
。如需 MIME 類型清單,請參閱「Google Workspace 和 Google 雲端硬碟支援的 MIME 類型」。
如果只想透過 MIME 類型搜尋「我的雲端硬碟」中的文件檔案,請附加下列查詢字串篩選器:
q: mimeType = 'application/vnd.google-apps.document'
如要進一步瞭解查詢字串篩選器,請參閱「搜尋檔案與資料夾」。
瞭解 documentId
後,請使用 documents.get
方法擷取指定文件的完整執行個體。詳情請參閱要求和回應。
如要匯出 Google Workspace 文件位元組內容,請將雲端硬碟的 files.export
方法與要匯出的 documentId
搭配使用,以及正確的匯出 MIME 類型。詳情請參閱「匯出 Google Workspace 文件內容」。
比較 Get
和 List
方法
下表說明雲端硬碟和文件方法之間的差異,以及兩者傳回的資料:
運算子 | 說明 | 用量 |
---|---|---|
drive.files.get |
根據 ID 取得檔案的中繼資料。傳回 files 資源的執行個體。 |
取得特定檔案的中繼資料。 |
drive.files.list |
取得使用者的檔案。傳回檔案清單。 | 如果您不確定需要修改哪個檔案,請先取得使用者檔案清單。 |
docs.documents.get |
取得指定文件的最新版本,包括所有格式和文字。傳回 documents 資源的執行個體。 |
取得特定文件 ID 的文件。 |
文件建立工作流程
建立新文件並簡化文件的程序相當簡單,因為現有的內容已不需要擔心,也沒有協作者可以變更文件狀態。就概念上而言,這在概念圖中如以下順序圖所示:
在圖 1. 中,與 documents
資源互動的使用者俱備下列資訊流程:
- 應用程式會在網路伺服器上呼叫
documents.create
方法。 - 網路伺服器傳送 HTTP 回應,其中包含所建立文件的執行個體做為
documents
資源。 - 視需要應用程式呼叫
documents.batchUpdate
方法,以不可分割的形式執行一組編輯要求,在文件中填入資料。 - 網路伺服器傳送 HTTP 回應。有些
documents.batchUpdate
方法會在回應主體中提供已套用要求的資訊,有些則顯示空白的回應。
文件更新工作流程
更新現有文件較為複雜。在發出有意義的呼叫以更新文件之前,您必須先瞭解文件目前的狀態:組成元素是什麼、這些元素的內容,以及文件中元素的順序。以下序列圖表說明運作方式:
在圖 2. 中,與 documents
資源互動的使用者俱有下列資訊流程:
- 應用程式會在網路伺服器上呼叫
documents.get
方法,並使用要尋找的documentId
檔案。 - 網路伺服器傳送 HTTP 回應,其中包含以
documents
資源形式指定文件的執行個體。傳回的 JSON 包含文件內容、格式和其他功能。 - 應用程式會剖析 JSON,以便使用者決定要更新的內容或格式。
- 應用程式會呼叫
documents.batchUpdate
方法,以不可分割的形式執行一組編輯要求來更新文件。 - 網路伺服器傳送 HTTP 回應。有些
documents.batchUpdate
方法會在回應主體中提供已套用要求的資訊,有些則顯示空白的回應。
這張圖未考量其他協作者在同一份文件中進行並行更新的工作流程。詳情請參閱「規劃協同合作」的最佳做法一節。