要求與回應

本指南將介紹 Google Docs API 的主要要求和回應方法,以及如何批次更新文件。

您可以透過 HTTP 要求或在語言專屬用戶端程式庫中使用方法叫用,藉此叫用 Google Docs API。這兩項指標相當大同小異。

Google Docs API 會傳回 HTTP 回應,當中通常包含要求叫用的結果。使用用戶端程式庫發出要求時,系統會以特定語言的方式傳回回應。

要求方法

Docs API 支援下列方法:

  • documents.create:建立空白的 Google 文件。
  • documents.get:傳回指定文件的完整例項。您可以剖析傳回的 JSON,以擷取文件內容、格式和其他功能。
  • documents.batchUpdate:提交編輯要求清單,以不可分割的形式套用至文件,然後傳回結果清單。

documents.getdocuments.batchUpdate 方法需要 documentId 做為參數來指定目標文件。documents.create 方法會傳回已建立文件的執行個體,方便您讀取 documentId。如要進一步瞭解 documentId,請參閱「文件 ID」。

批次更新

documents.batchUpdate 方法會使用 request 物件清單,每個物件分別指定要執行的一項要求。例如為段落設定格式 然後再新增內嵌圖片每個要求在套用前都會經過驗證,而會根據它們在批次要求中出現的順序進行處理。

系統會以不可分割的形式套用批次更新中的所有要求。也就是說,如果任何要求無效,整個更新就會失敗,且不會套用任何 (可能相依) 的變更。

部分 documents.batchUpdate 方法會提供回應,內含已套用要求的相關資訊。這些方法會傳回包含 response 物件清單的回應主體。其他要求則不需要傳回資訊及顯示空白回覆。回應清單中的物件具有與對應要求相同的索引順序。

以下是提出批次要求的熱門模式:

requests = []
requests.append(first request)
requests.append(second request)
...

body = ... & requests & ...

...batchUpdate(body)

想進一步瞭解如何批次處理 Docs API 呼叫,請參閱批次要求最佳做法;如要瞭解要求和回應類型,請參閱 documents.batchUpdate 參考說明文件。

批次更新作業

批次更新要求有多種類型,以下是要求類型的細目,細分為不同類別。

物件 新增 / 插入 更新 / 更換 刪除
文字 InsertTextRequest ReplaceAllTextRequest
風格 CreateParagraphBulletsRequest UpdateTextStyleRequest
UpdateParagraphStyleRequest
UpdateTableCellStyleRequest
UpdateTableRowStyleRequest
UpdateDocumentStyleRequest
UpdateSectionStyleRequest
DeleteParagraphBulletsRequest
已命名範圍 CreateNamedRangeRequest ReplaceNamedRangeContentRequest DeleteNamedRangeRequest
DeleteContentRangeRequest
圖像 InsertInlineImageRequest ReplaceImageRequest
資料表 InsertTableRequest
InsertTableRowRequest
InsertTableColumnRequest
UpdateTableColumnPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
PinTableHeaderRowsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
頁面物件 (包括headers頁尾) InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest
DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest