文件

本指南介紹的概念，例如構成 Google Docs API、文件存取方式和工作流程 文件。

API 方法

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

documents.get 和 documents.batchUpdate 方法需要 documentId 做為指定目標文件的參數。documents.create 方法 會傳回所建立文件的例項，您可以從中讀取 documentId。如要進一步瞭解 Docs API 要求，以及 回應方法，請參閱請求和 回應。

文件 ID

documentId 是文件的專屬 ID，可以用來衍生 從文件網址匯入文件這是一個特定字串，內含字母、數字和 一些特殊字元文件 ID 會保持固定，即使文件名稱也一樣 並輸入變更內容

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

下列規則運算式可用來從documentId Google 文件網址：

/document/d/([a-zA-Z0-9-_]+)

如果熟悉 Google Drive API，documentId 對應的是 id 在 files 資源中。

管理 Google 雲端硬碟中的文件

文件檔案會儲存在 Google 雲端硬碟，也就是雲端儲存空間 課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務Docs API 有自己的獨立方法， 必須使用 Google Drive API 方法，與使用者的 文件檔案。舉例來說，如要複製文件檔案，請使用 Drive API 的 files.copy 方法。詳情請參閱複製現有 文件。

根據預設，使用 Docs API 時，新文件會儲存至 使用者在 Google 雲端硬碟的根資料夾你可以透過多種方式儲存檔案 上傳至雲端硬碟資料夾詳情請參閱與 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 文件位元組的內容，請使用 Google 雲端硬碟 files.export 方法，搭配 要匯出檔案的 documentId 和正確匯出 MIME type：詳情請參閱「匯出 Google Workspace 文件 內容。

比較 Get 和 List 方法

下表列出雲端硬碟的差異 和各種文件中傳回的資料：

運算子 說明 用量
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 方法 提供回應主體，其中含有已套用要求的相關資訊，而 只會傳回空白回應

本圖表未考量其他並行更新作業的工作流程 協作者會加入同一份文件如需更多資訊，請參見 做法部分 合作無間