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 lets your users add comments and replies to documents created by your app. Collectively, a comment with replies is known as a discussion.
Add an unanchored comment
To add an unanchored comment to a document, call the comments.create
method with the fileId
parameter 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 the
replies.create
method with the comment,
fileId
parameter, and a replies
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 the
revisions.list
method to list everyrevisionID
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 the
comments.create
method with thefileID
parameter, 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 two-dimensional rectangle for an image, a line of text in a document,
or a time duration in a video. 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 the txt
or line
region classifier.
For a list of region classifiers in the Drive API, refer to 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 three lines ('l':3
). - The second area only covers line 18 (
'n':18, 'l':1
`).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Replace REVISION_ID with head
or the ID of a specific
revision.
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 dim all previous replies plus the original comment.
- Hide resolved comments.
Delete a comment
Use the comments.delete
method to
delete comments. When a comment is deleted, 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
.