爭取最佳成效的最佳做法

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

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

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

反向編輯以提高效率

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

規劃協作活動

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

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

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

使用 WriteControl 建立狀態一致性

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

步驟如下:

  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 秒 說明文件。