爭取最佳成效的最佳做法

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

  • 反向編輯以提高效率
  • 規劃協作活動
  • 使用 WriteControl 欄位確保狀態一致性

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

反向編輯以提高效率

在呼叫 documents.batchUpdate 方法的單次呼叫中，將要求依索引位置的遞減順序排序。如此一來，就不需要計算因插入和刪除而產生的索引變更。

規劃協作活動

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

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

這可能會導致索引錯誤。有多位使用者透過 UI 編輯文件，Google 文件會以公開透明的方式進行處理。不過，做為 API 用戶端，應用程式必須管理這項資訊。即使您預期文件不會參與協作，也務必要製定防禦機制，並確保文件狀態維持一致。要確保一致性的方法，請參閱 WriteControl 一節。

使用 WriteControl 建立狀態一致性

讀取並更新文件時，您可以使用 documents.batchUpdate 方法中的 WriteControl 欄位控制競爭變更的行為。WriteControl 可針對寫入要求執行的方式提供授權。

步驟如下：

  1. 使用 documents.get 方法取得文件，然後從傳回的 documents 資源中儲存 revisionId。
  2. 編寫更新要求。
  3. 加入選用的 WriteControl 物件，其中包含以下其中一個選項：
    1. requiredRevisionId 欄位會設為要套用寫入要求的文件 revisionId。如果文件在 API 讀取要求後遭到修改，系統就不會處理寫入要求，且會傳回錯誤。
    2. targetRevisionId 欄位設為要套用寫入要求的文件的 revisionId。如果在 API 讀取要求後修改文件，則寫入要求變更會套用至協作者變更。寫入要求的結果同時包含寫入要求變更，且協作者對文件的變更會納入文件的新修訂版本。文件伺服器會負責合併內容

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