Manage comments and replies

The Drive API allows you to add comments to files in Google Drive. You can let your users insert comments and replies in shared files and carry on discussion threads in the comments. You can support these features in your app to create an environment where users can share files and edit them collaboratively.

To learn about comments and discussions, watch the following video. Google engineers show you how to create comments and discuss tips and tricks.

Integrate comments and replies

When you use comments, you interact a lot with the comments and replies collections in addition to the files resource. In this model, a comment starts a discussion within a file, and replies are associated with a particular comment. Apps insert the content of both comments and replies as plain text, and then the response body provides an htmlContent field that contains content formatted for display.

In general, an app must make these API calls to manage comments:

  1. A files.get call any desired file metadata or content.
  2. A revisions.get call to get the revision of the current file that you work with. Use revisions.get(revisionId='head') to make sure you work with the latest revision. You need the revision id to anchor a comment to the file location.

  3. A comments.list call to retrieve the comments and replies in a file.

  4. A comments.create call to add the comment, or replies.create to add a reply to a current discussion.

Anchor a comment to a region of a document

When you insert a comment, you need to anchor it to a region in the file. An anchor defines the location or region in a file to which a comment relates or refers. Anchors are tied to a specific file revision. The Comments resource defines the anchor field as a JSON string that represents a region of a file.

You can also create classes of regions, see create a new classifier.

Anchors are tied to different regions for different files types, so apps should support regions that make sense for the file types they manipulate.

Some examples for regions to anchor comments per file type include:

  • Plain text documents — anchor the comment to comment line numbers.
  • Images — anchor the comment to a horizontal and vertical position.

Each anchor requires:

  • r — A string ID that indicates for which revision of the file this anchor was created. Use the revision id retrieved with revisions.get.
  • a — The region or regions associated with the anchor. This must be a JSON array, and the type of object in that array is a region.

You can define a region as an object with one or more region classifiers. Each region classifier is keyed by the classifier's name, and has a value that contains various fields suitable for that classifier.

Region classifiers

A region classifier defines the region format, for example: a two-dimensional rectangle image, a page number, a time duration in a video, a range of text characters, a line in a text file, or a row and column structure. Choose the region classifiers most suitable for your file type. Drive supports multiple classifiers for a single region. However, you cannot set the same region classifier twice in the same region.

rect

A rectangle in a two dimensional image.

Property Description Type
x Position on the x axis, units default to pixels for images and percent for PDFs. Double
y Position on the y axis, units default to pixels for images and percent for PDFs. Double
w Length on the x axis, units default to pixels for images and percent for PDFs. Double
h Length on the y axis, units default to pixels for images and percent for PDFs. Double
mw The full width of the document at the time when the comment was made. Use this to make x and w unitless since they can act like a percentage. Double
mh The height width of the document at the time when the comment was made. See mw above for purpose. Double
r The degrees of rotation of the document. E.g. if an image is rotated 90 degrees clockwise then a rectangle at 0,0 displays in the top right of the image. Should be one of 0, 90, 180, 270 Double
page

A page number in a pdf or tiff or other document with pages. Use this for documents with page-like elements (e.g. spreadsheets, slide, and layer).

Property Description Type
p The page number (0-indexed). Integer
mp The number of pages in this document. Integer
time

A duration of time in a video or other document with a time dimension | Integer

Property Description Type
t The start time. hh:MM:ss.frac formatted time string (where M = minutes, m = millis, hours and minutes are optional)
d The duration of the time range. hh:MM:ss:mmm formatted time string (where M = minutes, m = millis)
md The full time duration of the document. hh:MM:ss:mmm formatted time string (where M = minutes, m = millis)
txt

A range of text

Property Description Type
o Start offset (character offset from the start of the file). Integer
l The length of the text range. Integer
ml The length of this document in characters. Integer
line

A specific line in a text file or any files with lines in it.

Property Description Type
n Line number. Integer
l The length of the line range. Integer
ml The maximum number of lines in the file. Integer
matrix

A location in a matrix-like structure. Use to define row and columns in spreadsheet documents, or any other documents which have a row or column structure.

Property Description Type
c The column number. Integer
r The row number. Integer
w The number of columns. Integer
h The number of rows. Integer
mw The Maximum width. Integer
mh The Maximum height. Integer

This example shows a document that anchors comments to lines in two separate areas. The first area starts at line 12 and covers 3 lines, so it covers lines 12, 13, and 14. The second area starts at line 18, and only covers that one line. Text content for such a comment might be, "These lines are unnecessary. They are both covered by the text in line 4." In this example, 'n' represents the line number for the start of the comment, and 'l' represents the number of lines in the comment.

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

Create a new region classifier

If you want to create a new class of region, you should create a namespace for it with the app ID. For example, if your app has ID 1234 and creates a property called Slide, then the full classifier name would be 1234.Slide. That way if another app publishes another Slide, then the two would not collide. The blank namespace should only be used by Google-published classifiers.

Guidelines to process comments in a discussion

There are a few things to keep in mind when working with discussions: check permissions, resolve comments in some visible way, and don't display deleted comments unless you have a compelling reason to do so.

Permissions checks

Though it is not strictly required to manage comments, we recommend that you check permissions to ensure the current user has the permission to add comments to the document. Only the creator of a comment or reply can delete or edit a comment, and an app will receive errors if it tries to allow any other users to perform these operations. You can avoid error scenarios if you check the author.me field of a comments resource.

Create location in your UI for resolved comments

In the [comments]/drive/api/v3/reference/comments) resource, the resolved property can set whether or not a comment is resolved by one of its replies or not. If your app sets the resolved property when it inserts comments and replies, then your UI should give some clear indication of this status for users. One way to indicate this is to grey-out comments that get resolved. Another way is to hide resolved comment threads. For example, when a Google document marks a comment "resolved," it hides the comment from display.

Tombstones and deleted comments

When a user deletes a comment, Google Drive stores a "tombstone" of the comment, marked with "deleted": "true" in the comments resource. If your app retrieves some tombstoned comments with comments.list, you don't display them to the end user.

The Drive API provides the includedDeleted property for comments.list for exception cases. In particular, apps may want to use includedDeleted to make sure that the UI displays a current comments list, without any deleted comments. Consider this example flow:

  1. On load, list all comments except deleted ones (the default for includedDeleted is false). Store the current time right before you send this list request.
  2. Periodically perform a new list action and pass the saved timestamp as the startModifiedTime parameter to get the comments since your last request. In this case, set includeDeleted=true so that you can perform a diff between the existing and new comments lists.
  3. Based on that diff, update the UI to clear out newly deleted comments.

傳送您對下列選項的寶貴意見...

這個網頁
Drive REST API
Drive REST API
需要協助嗎?請前往我們的支援網頁