要求與回應

本指南將介紹 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 的參考說明文件，瞭解要求和回應類型。

批次更新作業

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

相關主題

• Google 文件的結構
• 結構性編輯規則和行為
• 批次要求