管理留言和回覆

註解是使用者針對檔案提供的意見回饋，例如文字處理文件的讀者建議如何改寫句子。註解分為兩種類型：錨定註解和非錨定註解。錨定註解會與特定位置 (例如文字處理文件中的句子) 相關聯，該位置位於文件的特定版本中。相反地，未錨定的註解只會與文件相關聯。

注意： 在 blob 檔案中，Google Drive API 僅支援未錨定的註解。系統不支援在 Blob 檔案或 Google 文件編輯器檔案中加上錨點註解。

回覆會附加至留言，代表使用者對留言的回應。Drive API 可讓使用者在應用程式建立的文件中新增註解和回覆。註解和回覆統稱為「討論」。

新增未錨定的註解

如要在文件中新增未錨定的註解，請使用 fileId 參數和含有註解的 comments 資源，呼叫 comments.create 方法。

註解會以純文字插入，但回應主體會提供 htmlContent 欄位，其中包含格式化供顯示的內容。

重要事項： 建議您確認使用者是否具備正確的權限，才能新增留言。此外，只有註解或回覆的作者才能刪除或編輯註解或回覆。當非創作者角色的使用者嘗試刪除或編輯留言時，就會發生錯誤。為避免發生這些錯誤，請檢查 comments 資源的 author.me 欄位，確認提出要求的使用者是留言作者，然後驗證他們對留言的權限。

新增回覆留言

如要為留言新增回覆，請使用留言、fileId 參數和包含回覆的 replies 資源，呼叫 replies.create 方法。

回覆會以純文字插入，但回應主體會提供 htmlContent 欄位，其中包含格式化供顯示的內容。

在文件的最新修訂版本中新增錨定註解

新增註解時，您可能會想將註解錨定至檔案中的某個區域。錨點會定義檔案中註解參照的檔案修訂版本和區域。comments 資源會將 anchor 欄位定義為 JSON 字串。

注意： 在 blob 檔案中，Drive API 僅支援未錨定的註解。不支援在 blob 檔案或 Google 文件編輯器檔案中使用錨點註解。

重要事項： 錨點不可變更，且在修訂版本之間，無法保證錨點相對於文件內容的位置。建議您在位置不會變動的文件中使用錨點，例如圖片檔案或唯讀文件。

如要新增錨定註解，請按照下列步驟操作：

1. (選用) 呼叫 revisions.list 方法，即可列出文件的每個 revisionID。只有在您想將註解繫結至最新修訂版本以外的修訂版本時，才需要執行這個步驟。如要使用最新修訂版本，請為 revisionID 使用 head。

2. 使用 fileID 參數、含有註解的 comments 資源，以及含有 revisionID (r) 和區域 (a) 的 JSON 錨點字串，呼叫 comments.create 方法。

定義區域的方式取決於您使用的文件內容類型。詳情請參閱「定義區域」。

注意： 建議您確認使用者是否具備正確的權限，才能新增留言。此外，只有註解或回覆的作者才能刪除或編輯註解或回覆。非創作者角色的使用者嘗試刪除或編輯留言時，系統會發生錯誤。為避免發生這些錯誤，請檢查 comments 資源的 author.me 欄位。

定義區域

如先前所述，JSON 錨點字串包含 revisionID (r) 和區域 (a)。區域 (a) 是包含區域分類器的 JSON 陣列，可指定註解的錨點格式和位置。分類器可能是圖片的二維矩形、文件中的一行文字，或影片中的一段時間。如要定義區域，請選取與要錨定的內容類型相符的區域分類器。舉例來說，如果您的內容是文字，您可能會使用 txt 或 line 區域分類器。

如需 Drive API 中的區域分類器清單，請參閱「區域分類器」。

以下範例顯示 JSON 錨點字串，可將註解錨定至文件中兩個區域的各行：

• 第一個區域從第 12 行 ('n':12) 開始，延伸至三行 ('l':3)。
• 第二個區域只涵蓋第 18 行 ('n':18, 'l':1`)。

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

將 REVISION_ID 替換為 head 或特定修訂版本的 ID。

重要事項： 如果您的應用程式允許使用者更新及分享文件的多個修訂版本，則舊版修訂版本的註解可能不再適用於錨定位置。因此，您必須在 UI 中清楚指出每則註解屬於哪個修訂版本。

解決註解

在解決註解後，請使用 comment.update 方法，將 comments 資源中的 resolved 屬性設為 true。

當應用程式將 resolved 屬性設為 true 時，使用者介面應會指出已處理該評論。舉例來說，您的應用程式可能會：

• 禁止進一步回覆，並將所有先前的回覆和原始留言調暗。
• 隱藏已解決的註解。

刪除留言

請使用 comments.delete 方法刪除留言。刪除留言後，雲端硬碟會將留言資源標示為 "deleted": "true"。

可列出註解

請使用 comments.list 方法列出留言。如果希望結果中包含已刪除的留言，請將 includedDeleted 欄位設為 true。