文件

本指南將介紹各種概念，例如組成 Google Docs API 的主要方法、文件存取方式，以及建立文件的工作流程。

API 方法

documents 資源提供用來叫用 Docs API 的方法。您可以使用下列方法建立、讀取及更新 Google 文件文件：

• 使用 documents.create 方法建立文件。
• 使用 documents.get 方法擷取指定文件的內容。
• 使用 documents.batchUpdate 方法，在指定文件上以不可分割的方式執行一組更新。

documents.get 和 documents.batchUpdate 方法需要 documentId 做為參數，以指定目標文件。documents.create 方法會傳回已建立文件的例項，您可以從中讀取 documentId。如要進一步瞭解 Docs 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 雲端硬碟 (即雲端式儲存空間服務) 中。雖然 Docs API 有獨立方法，但通常也需要使用 Google Drive API 方法與使用者的文件檔案互動。舉例來說，如要複製 Docs 檔案，請使用 Drive API 的 files.copy 方法。詳情請參閱「複製現有文件」。

根據預設，使用 Docs 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 和 Docs 方法之間的差異，以及各方法會傳回的資料：

文件建立工作流程

建立及填入新文件的程序相當簡單，因為沒有現有內容需要擔心，也沒有任何協作者可以變更文件狀態。從概念上來說，這運作方式如下圖所示：

在圖 1 中，使用者與 documents 資源互動時，會有以下資訊流程：

1. 應用程式會在網路伺服器上呼叫 documents.create 方法。
2. 網路伺服器會傳送 HTTP 回應，其中包含已建立文件的例項，做為 documents 資源。
3. 應用程式可視需要呼叫 documents.batchUpdate 方法，以不可分割的方式執行一組編輯要求，為文件填入資料。
4. 網路伺服器會傳送 HTTP 回應。部分 documents.batchUpdate 方法會提供回應主體，其中包含已套用要求的相關資訊，其他方法則會顯示空白回應。

文件更新工作流程

更新現有文件的程序較為複雜。您必須先瞭解文件的目前狀態，才能發出有意義的呼叫來更新文件，包括文件的組成元素、這些元素的內容，以及文件中元素的順序。下列時序圖說明這項功能的運作方式：

在圖 2 中，使用者與 documents 資源互動時，會有以下資訊流程：

1. 應用程式會在網路伺服器上呼叫 documents.get 方法，並使用要尋找的 documentId 檔案。
2. 網路伺服器會傳送 HTTP 回應，其中包含指定文件的例項，做為 documents 資源。傳回的 JSON 包含文件內容、格式和其他功能。
3. 應用程式會剖析 JSON，讓使用者決定要更新哪些內容或格式。
4. 應用程式會呼叫 documents.batchUpdate 方法，以不可分割的方式執行一組編輯要求，藉此更新文件。
5. 網路伺服器會傳送 HTTP 回應。部分 documents.batchUpdate 方法會提供回應主體，其中包含已套用要求的相關資訊，其他方法則會顯示空白回應。

這張圖表並未考量到在同一份文件中，其他協作者同時進行更新的流程。詳情請參閱「協作規劃」一節的最佳做法。

相關主題

• Google 文件的結構
• 要求與回應
• 結構性編輯規則和行為
• 獲得最佳成果的最佳做法