要求與回應

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

您可以使用 HTTP 要求，或在語言專屬的用戶端程式庫中使用方法叫用來叫用 Google 文件 API。這兩種方法大致相同。

Google 文件 API 會傳回 HTTP 回應，通常會包含要求叫用作業的結果。使用用戶端程式庫發出要求時，系統會以語言專屬的方式傳回回應。

要求方法

Docs API 支援下列方法：

  • documents.create：建立空白的 Google 文件。
  • documents.get：傳回指定文件的完整例項。您可以剖析傳回的 JSON，擷取文件內容、格式和其他功能。
  • documents.batchUpdate：提交編輯要求清單，以便以原子方式套用至文件，並傳回結果清單。

documents.get 和 documents.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)

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

批次更新作業

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

物件 ADD / INSERT 更新 / 取代 刪除
文字 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
頁面物件 (包括頁首和頁尾) InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest		 DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest