爭取最佳成效的最佳做法

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

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

考量分頁

單一文件可包含多個分頁，因此您必須在 API 要求中特別處理。

請注意以下事項：

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