コメントおよびリプライを管理する

みるくあいらんどっ! > 和訳 > google関係 > Drive API > api > v3


  • この記事は、Google Drive™ APIに関する記事を和訳したものです。
  • 原文: Manage comments and replies
  • 元記事のライセンスは CC-BYで、この和訳記事のライセンスは CC-BYです。
  • 自己責任でご利用ください。
  • 和訳した時期は 2019年6月ころです。

Drive APIは、Google Drive内のファイルにコメントを追加できるようにします。 ユーザに、共有されたファイル内にコメントおよびリプライを挿入させ、コメントに議論スレッドを続行させることができます。 あなたのアプリにこれらの機能をサポートすることによって、ユーザがファイルを共有し、それらを共同で編集することができる環境を作成することができます。

コメントおよびリプライを操作する

コメントを操作するとき、ファイルリソースに加えて、commentsおよび repliesを用いて多くの相互作用をするでしょう。 このモデルでは、コメントはファイル内で議論を開始し、リプライは特定のコメントと関連付けられます。 アプリは、コメントとリプライの両方のコンテンツを、プレーンテキストとして挿入し、それから、レスポンスボディは、表示のためにフォーマットされたコンテンツを含む htmlContentフィールドを提供します。

これらのリソースの使用方法の詳細と例については、API referenceを参照してください。

一般的に、アプリは、コメントを管理するとき、次の API呼び出しを行わなければなりません:

  1. files.get任意の望むファイルのメタデータあるいはコンテンツを呼び出します。
  2. revisions.getは、現在作業しているファイルのリビジョンを取得するために呼び出します。 最新のバージョンを用いて作業していることを確認するには、revisions.get(revisionId=#39;head#39;) を使用します。 "anchors" (後述)を用いて作業するには、リビジョン idを必要とするでしょう。
  3. comments.listは、ファイル内のコメントおよびリプライを取得するために呼び出します。
  4. comments.createは、コメントを追加するために呼び出します、あるいは、既存の議論にリプライを追加するために replies.createを呼び出します。

コメントを挿入するとき、ファイル内の領域にコメントをアンカーすることを考慮する必要があるでしょう。 アンカーのための参考情報はこのページで後述されます、それは、カスタムスキーマを作成する幾つかのヒントを伴います。

コメントをアンカーする

アンカーは、コメントが関連あるいは参照する、ファイル内の位置あるいは領域を定義します。 アンカーはファイルの特定のリビジョンに関連付けられます。

アンカーは、異なるファイルのタイプのために異なる領域に関連付けられており、アプリは、操作するファイルタイプに合った領域をサポートする必要があります。 例えば、行番号にコメントをアンカーすることはプレーンテキストのドキュメントには合っていますが、垂直および水平の位置にそれらをアンカーすることは画像により合っています。

それぞれのアンカーは、2つの必要とされるプロパティを持っています:

  • r — このアンカーが作成されたファイルのリビジョンを示す文字列 ID。 revisions.getを用いて取得されたリビジョン idを使用します。
  • a — これは、JavaScript配列でなければならず、その配列内のオブジェクトのタイプは領域です。

ひとつあるいは複数の領域分類子を伴うオブジェクトとして、領域を定義することができます。 それぞれの領域分類子は、分類子の名前によってキーされていて、その分類子のために適したさまざまなプロパティを含む値を持っています。 例えば、ドキュメントにて行によってコメントをアンカーすることは、次のようになるかもしれません: 

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

これは、2つの別々の領域にコメントをアンカーしています: 12行目は、3行の範囲をカバーし、18行目も同様にカバーしています。 そのようなコメントのテキストコンテンツは、"These lines are unnecessary. They are both covered by the text in line 4." であるかもしれません。

サポートされる領域分類子

あなたのファイルタイプに最も適した領域分類子を選択します。 Driveは、単一の領域のために複数の分類子をサポートしています。 しかしながら、同じ領域に同じ領域分類子を 2度セットすることはできません。

rect

2次元画像の四角形。

プロパティ 説明 タイプ
x X軸上の位置、単位は、画像の場合はピクセル、PDFの場合はパーセントをデフォルトとします。 Double
y Y軸上の位置、単位は、画像の場合はピクセル、PDFの場合はパーセントをデフォルトとします。 Double
w X軸上の長さ、単位は、画像の場合はピクセル、PDFの場合はパーセントをデフォルトとします。 Double
h Y軸上の長さ、単位は、画像の場合はピクセル、PDFの場合はパーセントをデフォルトとします。 Double
mw コメントが作られたとき文書の全幅。 これは、それらをパーセンテージのように動作することができるので、xおよび wを単位無しにするために使用されることができます。 Double
mh コメントが作られたときの文書の高さの幅。 目的については、上記の mwを参照してください。 Double
r ドキュメントの回転の度合い。 例えば、もし画像が時計回りに 90度回転されているならば、四角形の 0,0 は、表示された画像の右上に表示されるでしょう。 0, 90, 180, 270のいずれかである必要があります Double
page

PDFあるいは TIFF、あるいはページを伴う他のドキュメント内のページ番号。 ページのような要素を伴うドキュメントにも使用される必要があります。 例えば、シート(spreadsheetsのための)、スライド、レイヤーなど。

プロパティ 説明 タイプ
p ページ番号(0インデックスされた)。 Integer
mp このドキュメントのページ数。 Integer
time

動画、あるいは時刻の次元をを伴う他のドキュメント内の時間の期間

プロパティ 説明 タイプ
t 開始時間。 hh:MM:ss.frac形式の時間文字列(M = 分、m = ミリ秒、時および分はオプション)
d 時間範囲の継続時間。 hh:MM:ss:mmm形式の時間文字列(M = 分、m = ミリ秒)
md ドキュメントの全時間。 hh:MM:ss:mmm形式の時間文字列(M = 分、m = ミリ秒)
txt

テキストの範囲

プロパティ 説明 タイプ
o 開始オフセット(ファイルの開始からの文字オフセット)。 Integer
l テキスト範囲の長さ。 Integer
ml このドキュメントの文字での長さ。 Integer
line

テキストファイル、あるいはその中に行を伴う他のファイル内の、特定の行。

プロパティ 説明 タイプ
n 行番号。 Integer
l 行の範囲の長さ。 Integer
ml ファイル内の行の最大数。 Integer
matrix

行列のような構造内の位置。 スプレッドシートドキュメント内の行および列、あるいは、行/列構造を持つ他のドキュメントを定義するのに役立ちます。

プロパティ 説明 タイプ
c 列番号。 Integer
r 行番号。 Integer
w 列の数。 Integer
h 行の数。 Integer
mw 最大幅。 Integer
mh 最大高さ。 Integer

カスタムスキーマ

もし領域の新しいクラスを作成したければ、アプリ IDによってそれに名前を付ける必要があります。 例えば、もしあなたのアプリが ID 1234を持っており、Slideと呼ばれるプロパティを作成するならば、完全な分類子の名前は 1234.Slideになるでしょう。 そうすれば、異なるアプリが他の Slideを公開した場合に、2つは衝突しないでしょう。 空の名前空間は、Googleが公開した分類子によってのみ使用される必要があります。

議論を操作するためのペストプラクティス

議論を操作するとき、心に留めておく少しのことがあります: パーミッションをチェックし、幾つかの表示可能な方法にてコメントを解決し、それをする魅力的な理由がない限り、削除したコメントを表示しません。

パーミッションのチェック

コメントを管理するために厳密には必要とはされませんが、パーミッションをチェックすることを強くお勧めします。 コメントあるいはリプライの作成者のみが、コメントを削除あるいは編集することができ、他のユーザがこれらの操作を実行できるようにしようとする場合、アプリはエラーを受け取るでしょう。 コメントリソースの author.meフィールドをチェックすることによって、エラーシナリオを回避することができます。

解決されたコメントのための UI

もし、コメントおよびリプライを挿入するとき、あなたのアプリが resolvedプロパティをセットするならば、あなたの UIは、ユーザのためにこの状態を明確に示す必要があります。 例えば、解決されたコメントはグレー表示されるかもしれません、あるいは、(Googleドキュメントのように)解決されたコメントのスレッドは、表示されたファイルから削除される可能性があります。

墓石および削除されたコメント

ユーザがコメントを削除したとき、Google Driveは、コメントの "tombstone" を格納します、それは、コメントリソースにて "deleted": "true" とマークされています。 もしあなたのアプリが comments.listを用いて幾つかの墓石となったコメントを取得するならば、恐らく、エンドユーザにそれらを表示すべきではないでしょう。

Drive APIは、例外のケースのために、comments.listのために includedDeletedプロパティを提供します。 特に、アプリは、UIが現在のコメントリストを表示することを保証するために、includedDeletedを使用したいかもしれません、それは、削除されたコメントなしです。 このフローは、次のようになるかもしれません:

  1. 読み込み時、すべてのコメントをリストします、もちろん、削除されたものを除きます(includedDeletedのデフォルトは falseです)。 このリストのリクエストを送信する直前に、現在の時刻を格納します。
  2. 定期的に新しいリストアクションを実行し、あなたの最後のリクエスト以降のコメントを取得するために、startModifiedTimeパラメータとして保存されたタイムスタンプを渡します。 この場合、includeDeleted=true をセットするので、既存のものと新しいコメントリストとの間の diff を実行することができます。
  3. その diff に基づいて、新しく削除されたコメントをクリアするよう、UIを更新します。

ヒントとテクニック

コメントおよび議論の詳細については、Googleのエンジニアが関連するヒントとテクニックを議論している次の動画をご覧ください。