爭取最佳成效的最佳做法

使用 Google 文件 API 時，請遵守下列幾項原則。 包括：

  • 倒帶編輯，提高效率
  • 規劃協作
  • 使用 WriteControl 欄位確保狀態一致性
  • 將分頁納入考量

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

倒帶編輯，提高效率

在單次呼叫 documents.batchUpdate 方法時，請依索引位置遞減順序排序要求。這樣就不必計算因插入和刪除而造成的索引變更。

規劃協作

文件狀態應會變更。在一個方法呼叫和另一個方法呼叫之間，其他協作者可能會更新文件，如下圖所示：

文件在方法呼叫之間可能發生的變化。

如果索引有誤，可能會導致錯誤。如果多位使用者透過使用者介面編輯文件，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 建構批次要求，請參閱這個批次要求範例。

將分頁納入考量

單一文件可以包含多個分頁，因此 API 要求必須經過特定處理。

請注意以下事項：

  1. 在 documents.get 方法中將 includeTabsContent 參數設為 true，即可從文件中的所有分頁擷取內容。根據預設，系統不會傳回所有分頁內容。
  2. 在 documents.batchUpdate 方法中，指定要套用每個 Request 的索引標籤 ID。每個 Request 都包含指定要套用更新的索引標籤方式。根據預設，如果未指定分頁，Request 大部分會套用至文件中的第一個分頁。詳情請參閱 Request 說明文件。