Comments are user-provided feedback on a file, such as a reader of a word processing document suggesting how to rephrase a sentence. There are two types of comments: anchored comments and unanchored comments. An anchored comment is associated with a specific location, such as a sentence in a word processing document, within a specific version of a document. Conversely, an unanchored comment is just associated with the document.
Replies are attached to comments and represent a user's response to the comment. The Drive API enables you to allow your users to add comments and replies to documents created by your app. Collectively, a comment with replies is known as a discussion.
For a full synopsis of the Drive API's commenting API, watch the following video:
Add an unanchored comment
To add an unanchored comment to a document, call
comments.create
with the fileId
and a comments
resource containing
the comment.
The comment is inserted as plain text, but the response body provides an
htmlContent
field containing content formatted for display.
Add a reply to a comment
To add a reply to a comment, call
replies.create
with the comment,
fileId
, and a reply
resource
containing the reply.
The reply is inserted as plain text, but the response body provides an
htmlContent
field containing content formatted for display.
Add an anchored comment to the latest revision of a document
When you add a comment, you might want to anchor it to a region in the file.
An anchor defines the file revision and region in a file to which
a comment refers. The Comments
resource defines the anchor
field as a JSON string.
To add an anchored comment:
(Optional). Call revisions.list to list all of the
revisionID
s for a document. Only follow this step if you want to anchor a comment to any revision other than the latest revision. If you want to use the latest revision, usehead
for therevisionID
.Call
comments.create
with thefileID
, acomments
resource containing the comment, and a JSON anchor string containing therevisionID
(r
) and region (a
).
How you define a region depends on the type of document content you are working with. For further information, refer to Define a region.
Define a region
As mentioned earlier, the JSON anchor string contains a revisionID
(r
) and
region (a
). The region (a
) is a JSON array containing
region classifiers specifying the format and location to which a comment
is anchored. A classifier might be a as a two-dimensional rectangle for an
image, a line of text in a document, a time duration in a video, and so on.
To define a region, select the region classifier that matches the
type of content you are trying to anchor to. For example, if your content is
text, you are likely going to use either txt
or line
region classifier.
For a list of region classifiers provided in the Google Drive API, refer to Google Drive API region classifiers.
The following example shows a JSON anchor string that anchors comments to lines in two separate areas of a document:
- The first area starts at line 12 (
'n':12
) and extends for 3 lines ('l':3
). - The second area only covers line 18 (
'n':12, 'l':
`).
{
'r': revisionId,
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Google Drive API region classifiers
Following is a list of all of the region classifiers included with the Drive API:
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
andw
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
Resolve a comment
Use the comment.update method to set the resolved
property in the
comments resource to true
when a
comment has been addressed.
When your app sets the resolved
property to true
, your UI should indicate
that the comment has been addressed. For example, your app might:
- disallow further replies and greying out all previous replies and the original comment.
- hide resolved comments.
Delete a comment
Use the comments.delete method to delete
comments. When a comment is deleted, Google Drive marks the comment resource as
"deleted": "true"
.
List comments
Use the comments.list method to list
comments. If you want to include deleted comments in the results, set
the includedDeleted
field to true
.