文件

本指南將介紹 Google 文件 API 的主要方法、如何存取文件，以及建立文件時的工作流程等概念。

API 方法

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

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 雲端硬碟 API，documentId 會對應至 files 資源中的 id。

管理 Google 雲端硬碟中的文件

文件檔案會儲存在 Google 雲端硬碟中，這是我們的雲端儲存服務。雖然 Docs API 有其獨立的方法，但通常也需要使用 Google Drive API 方法，才能與使用者的 Docs 檔案互動。舉例來說，如要複製 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 方法之間的差異，以及各方法會傳回的資料：

運算子 說明 用量
drive.files.get 根據 ID 取得檔案的中繼資料。傳回 files 資源的例項。 取得特定檔案的中繼資料。
drive.files.list 取得使用者的檔案。傳回檔案清單。 如果不確定要修改哪個檔案，請取得使用者檔案清單。
docs.documents.get 取得指定文件的最新版本，包括所有格式和文字。傳回 documents 資源的例項。 取得特定文件 ID 的文件。

文件建立工作流程

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

建立及填入新文件的工作流程。
圖 1. 建立及填入新文件的工作流程。

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

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

文件更新工作流程

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

更新文件的工作流程。
圖 2. 更新文件的工作流程。

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

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

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