爭取最佳成效的最佳做法

使用 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 讀取要求後修改文件，則寫入要求變更會套用至協作者變更。寫入要求的結果會將寫入要求變更和協作者變更納入文件的新修訂版本。Docs 伺服器會負責合併內容。

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

將分頁納入考量

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

請注意以下事項：

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