管理留言和回覆

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

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

使用 fields 參數

在 comments 資源上，您必須為所有方法 (delete 除外) 設定 fields 系統參數，指定要在回應中傳回的欄位。在大多數的雲端硬碟資源方法中，這項動作僅用於傳回非預設欄位，但對於 comments 資源而言，這是必要動作。如果省略 fields 參數，這個方法會傳回錯誤。詳情請參閱「傳回特定欄位」。

留言限制

使用 Drive API 處理錨定和未錨定的註解時，系統會強制執行下列限制：

留言類型	檔案類型
錨定	開發人員可以自行定義錨點規格的格式。 系統會在擷取註解時儲存並傳回錨點，但 Google Workspace 編輯器應用程式會將這些註解視為未錨定的註解。
未錨定	Google Workspace 文件支援這項功能，並會在「所有註解」檢視畫面中顯示註解。 在雲端硬碟檔案預覽器中，系統不會顯示未錨定的註解，但這些註解會儲存起來，並可透過雲端硬碟 API 擷取。

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

新增註解時，您可能想將註解錨定在檔案中的特定區域。錨點會定義檔案中註解參照的區域。comments 資源會將 anchor 欄位定義為 JSON 字串。

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

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

1. (選用) 呼叫 revisions 資源上的 list 方法，列出文件的所有 revisionID。如要將留言錨定至最新修訂版本以外的任何修訂版本，才需要執行這個步驟。如要使用最新修訂版本，請對 revisionID 使用 head。

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

以下程式碼範例說明如何建立錨定註解：

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

Drive API 會傳回 comments 資源物件的執行個體，其中包含 anchor 字串。

注意： 建議您確認使用者是否具備新增留言的正確權限。此外，只有註解或回覆的建立者可以刪除或編輯註解或回覆。如果使用者不是建立者，嘗試刪除或編輯留言時就會發生錯誤。為避免發生這些錯誤，請檢查author.me留言資源的欄位。

新增未錨定的註解

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

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

以下程式碼範例說明如何建立未錨定的留言：

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

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

回覆留言

如要回覆留言，請使用 replies 資源的 create 方法，並加上 fileId 和 commentId 參數。要求主體會使用 content 欄位新增回覆。

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

這個方法會傳回 fields 欄位中列出的欄位。

要求

在本範例中，我們提供 fileId 和 commentId 路徑參數，以及多個欄位。

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

要求主體

{
  "content": "This is a reply to a comment."
}

解決註解

如要解決留言問題，只能回覆留言。

如要解決留言，請使用 replies 資源的 create 方法，並搭配 fileId 和 commentId 參數。

要求主體使用 action 欄位來解決留言。您也可以設定 content 欄位，新增會關閉留言的回覆。

註解解決後，雲端硬碟會將 comments 資源標示為 resolved: true。與已刪除的註解不同，已解決的註解可以包含 htmlContent 或 content 欄位。

應用程式解決留言問題後，UI 應指出留言已處理完畢。舉例來說，您的應用程式可能：

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

要求

在本範例中，我們提供 fileId 和 commentId 路徑參數，以及多個欄位。

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

要求主體

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

取得留言

如要取得檔案的留言，請使用 comments 資源的 get 方法，並搭配 fileId 和 commentId 參數。如果您不知道留言 ID，可以使用 list 方法列出所有留言。

這個方法會傳回 comments 資源的執行個體。

如要在結果中納入已刪除的留言，請將 includedDeleted 查詢參數設為 true。

要求

在本範例中，我們提供 fileId 和 commentId 路徑參數，以及多個欄位。

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

列出註解

如要列出檔案的註解，請使用 comments 資源的 list 方法，並搭配 fileId 參數。這個方法會傳回註解清單。

傳遞下列查詢參數，即可自訂留言的分頁或篩選條件：

• includeDeleted：設為 true 即可納入已刪除的留言。已刪除的留言不包含 htmlContent 或 content 欄位。

• pageSize：每頁要傳回的留言數量上限。

• pageToken：屬於接收自前一個清單呼叫的網頁權杖。提供此權杖即可擷取後續網頁。

• startModifiedTime：結果註解的 modifiedTime 欄位最小值。

要求

在本例中，我們提供 fileId 路徑參數、includeDeleted 查詢參數和多個欄位。

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

更新留言

如要更新檔案的註解，請使用 comments 資源的 update 方法，並搭配 fileId 和 commentId 參數。要求主體會使用 content 欄位更新留言。

comments 資源上的布林值 resolved 欄位為唯讀。如要解決留言問題，只能回覆留言。詳情請參閱「解決留言」。

這個方法會傳回 fields 查詢參數中列出的欄位。

要求

在本範例中，我們提供 fileId 和 commentId 路徑參數，以及多個欄位。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

要求主體

{
  "content": "This comment is now updated."
}

刪除留言

如要刪除檔案的留言，請在 comments 資源上使用 delete 方法，並搭配 fileId 和 commentId 參數。

刪除留言後，雲端硬碟會將留言資源標示為 deleted: true。刪除的留言不包含 htmlContent 或 content 欄位。

要求

在本範例中，我們提供 fileId 和 commentId 路徑參數。

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID

相關主題

• 檔案和資料夾總覽
• 管理檔案修訂版本