Google Docs API 可讓您建立及修改文件。
應用程式可以與 Docs API 整合,以根據使用者和系統提供的資料建立精美文件。您可以使用這個 API 執行下列操作:
- 自動化程序
- 大量建立說明文件
- 產生月結單或合約
API 總覽
documents 資源提供用來叫用 Document API 的方法。
API 方法
下列方法可讓您建立、讀取及更新 Google 文件:
- 使用 documents.create 建立文件。
- 使用 documents.get 擷取指定文件的內容。
- 使用 documents.BatchUpdate 以不可分割的形式對指定文件執行一組更新。
get
和 batchUpdate
方法需要 documentId
(請見下文) 做為參數來指定目標文件。create
方法會傳回已建立文件的執行個體,方便您讀取 ID。
批次更新
batchUpdate
方法會取得要求物件清單,並按照批次要求中顯示的順序進行更新。系統會以不可分割的形式套用批次更新中的更新。也就是說,如有任何要求無效,整個更新作業都會失敗,系統也不會套用任何 (可能依附的) 變更。
batchUpdate
方法會傳回回應物件清單。這份清單中的物件具有與對應要求相同的索引順序。
如要瞭解如何同時批次處理 API 呼叫,請參閱批次要求最佳做法,以及要求和回應類型的 BatchUpdate 參考說明文件。
文件 ID
文件 ID 會參照文件,而且可以從網址取得:
https://docs.google.com/document/d/documentId/edit
documentId
是包含字母、數字和某些特殊字元的不重複字串。以下規則運算式可用來從 Google 文件網址擷取文件 ID:
/document/d/([a-zA-Z0-9-_]+)
如果您熟悉 Google Drive API,documentId
會對應至檔案資源的 ID。
文件中的位置:索引
當您更新文件內容時,每次更新都會在文件中的某個位置或範圍內進行。這些位置和範圍是以「索引」指定,索引代表包含文件區段中的偏移量。如要進一步瞭解索引及其使用方式,請參閱 Google 文件文件的結構概念指南。
文件更新工作流程
建立新文件和填入新文件相當簡單,因為沒有需要擔心的現有內容,且沒有任何協作者可以變更文件狀態。概念上來說,這如下列序列圖所示:
更新現有文件較為複雜。您必須先瞭解文件的目前狀態:包含哪些元素、這些元素的內容,以及這些項目在文件中的位置,才能進行有意義的呼叫以更新文件。以下序列圖說明運作方式:
在同一份文件中,其他協作者同時進行並行更新時,此圖表不考慮相關工作流程。有關這個主題的討論,請參閱規劃協同合作。