コメントとは、ファイルに関してユーザーが入力するフィードバックです。たとえば、文章の言い換え方法を提案するワード プロセッシング ドキュメントの閲覧者からのフィードバックです。コメントには、固定コメントと固定コメントの 2 種類があります。アンカーコメントは、ドキュメントの特定バージョン内の特定の場所(ワープロ ドキュメントの文など)に関連付けられます。反対に、固定されていないコメントは単にドキュメントに関連付けられます。
返信はコメントに添付され、コメントに対するユーザーの返信を表します。Drive API を使用すると、ユーザーは、アプリによって作成されたドキュメントにコメントや返信を追加できます。返信付きのコメントを「ディスカッション」と呼びます。
固定されていないコメントを追加する
固定されていないコメントをドキュメントに追加するには、fileId
パラメータとコメントを含む comments
リソースを指定して、comments.create
メソッドを呼び出します。
コメントは書式なしテキストとして挿入されますが、レスポンスの本文には表示用にフォーマットされたコンテンツを含む htmlContent
フィールドがあります。
コメントに返信を追加する
コメントに返信を追加するには、コメント、fileId
パラメータ、返信を含む replies
リソースを指定して、replies.create
メソッドを呼び出します。
返信は書式なしテキストとして挿入されますが、レスポンスの本文には表示用にフォーマットされたコンテンツを含む htmlContent
フィールドがあります。
ドキュメントの最新リビジョンにアンカーコメントを追加する
コメントを追加するときに、ファイル内の領域に固定できます。アンカーは、コメントが参照するファイル内のファイルのリビジョンとリージョンを定義します。comments
リソースは、anchor
フィールドを JSON 文字列として定義します。
固定コメントを追加するには:
(省略可)
revisions.list
メソッドを呼び出して、ドキュメントのすべてのrevisionID
を一覧表示します。この手順は、最新のリビジョン以外のリビジョンにコメントを固定する場合にのみ行ってください。最新のリビジョンを使用する場合は、revisionID
にhead
を使用します。fileID
パラメータ、コメントを含むcomments
リソース、revisionID
(r
)とリージョン(a
)を含む JSON アンカー文字列を指定して、comments.create
メソッドを呼び出します。
リージョンの定義方法は、扱うドキュメント コンテンツの種類によって異なります。詳細については、リージョンを定義するをご覧ください。
地域を定義する
前述のように、JSON アンカー文字列には revisionID
(r
)とリージョン(a
)が含まれます。リージョン(a
)は、コメントが固定される形式と場所を指定するリージョン分類子を含む JSON 配列です。分類器には、画像用の 2 次元の長方形、ドキュメント内のテキスト行、動画内の再生時間などがあります。地域を定義するには、アンカー先のコンテンツの種類と一致する地域分類を選択します。たとえば、コンテンツがテキストの場合は、txt
または line
のリージョン分類器を使用する可能性が高くなります。
Drive API の地域分類器の一覧については、地域分類器をご覧ください。
次の例は、ドキュメント内の 2 つの別々の領域にある行にコメントを固定する JSON アンカー文字列を示しています。
- 最初の領域は 12 行目(
'n':12
)から始まり、3 行('l':3
)になります。 - 2 番目の領域は 18 行目(
'n':18, 'l':1
)のみをカバーします。
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
REVISION_ID は、head
または特定のリビジョンの ID に置き換えます。
コメントを解決する
コメントに対処したときに、comment.update
メソッドを使用して comments
リソースの resolved
プロパティを true
に設定します。
アプリで resolved
プロパティを true
に設定すると、UI でコメントに対処済みであることが示されます。たとえば、アプリは次のようなものです。
- それ以降の返信を禁止し、以前の返信と元のコメントをすべてグレー表示にする。
- 解決済みのコメントを非表示にする。
コメントを削除する
コメントを削除するには、comments.delete
メソッドを使用します。コメントが削除されると、ドライブはそのコメント リソースを "deleted": "true"
としてマークします。
コメントを一覧表示する
comments.list
メソッドを使用して、コメントを一覧表示します。削除されたコメントを結果に含める場合は、includedDeleted
フィールドを true
に設定します。