爭取最佳成效的最佳做法

使用 Google Docs API 時，請遵守以下幾項原則。 包括：

  • 反向編輯以提高效率
  • 規劃協作活動
  • 使用 WriteControl 欄位
  • 將分頁納入考量

以下各節將說明這些原則。

反向編輯以提高效率

在對 documents.batchUpdate 方法，請將要求以 索引位置的「遞減排序」。如此一來 系統因插入和刪除作業而變更索引。

規劃協作活動

預計要變更文件狀態。在其中一種方法呼叫之間 協作者可能會更新文件，如下圖所示：

文件如何在方法呼叫之間變更。

這可能會導致索引錯誤。多人編輯一個 文件，Google 文件會以公開透明的方式進行處理。不過 做為應用程式必須管理這個 API 用戶端即使您沒預期 共同發展文件時，務必制定防禦機制 請確保文件狀態保持一致如要確保一致性 請查看「WriteControl」部分。

使用 WriteControl 建立狀態一致性

閱讀和更新文件時，你可以控管 競爭變更則是透過 WriteControl 欄位。documents.batchUpdate「WriteControl」提供主管機關 管理寫入要求的方式

步驟如下：

  1. 使用 documents.get 方法並儲存 這個 revisionId 來自傳回的 documents 資源中。
  2. 編寫更新要求。
  3. 加入選用 WriteControl 含有以下兩個選項之一的物件：
    1. requiredRevisionId 欄位設為revisionId 並記錄適用的寫入要求如果文件是否經過修改 因此系統不再處理寫入要求 傳回錯誤。
    2. targetRevisionId 欄位已設為文件的 revisionId 寫入要求如果文件自 API 讀取要求，寫入要求變更會套用至 協作者變更內容。寫入要求的結果包含 寫入要求變更，而協作者變更為新的 修訂內容Google 文件伺服器負責 合併內容

如需如何使用 WriteControl 建構批次要求的範例，請參閱 這個批次要求範例。

將分頁納入考量

單一文件可包含多個分頁， 在 API 要求中需要特定處理方式。

注意事項：

  1. 將 includeTabsContent 參數設為 true： 將 documents.get 方法指派給自己 從文件中所有分頁擷取內容。根據預設，非所有分頁 內容。
  2. 指定要套用各個 Request 的分頁 ID 目標位置：documents.batchUpdate 方法。每個 Request 包括指定要套用更新的分頁。根據預設 未指定 Tab 鍵，Request 在多數情況下，這類標籤會套用在文件的第一個分頁。詳情請參閱 Request 秒 說明文件。