爭取最佳成效的最佳做法

使用 Google Document 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 建構批次要求的範例，請參閱這個批次要求範例。