ノート機能 #

はじめに #

この文書では daab SDK のノート機能の仕様について説明します。

大枠として、ノートの作成はこれまで通り Hubot の send メソッドを使用し、それ以外の操作 (取得、更新、削除) については robot.direct.notes から提供される各種 API を使用します。

ノートの作成 #

テキストノートの作成 #

以下のコードは従来通りの (スタイルがない) ノートを作成します。

robot.hear(/note$/, (res) => {
  res.send({
    note_title: 'タイトル',
    note_content: 'コンテンツ',
  });
});

指定するフィールドの仕様は以下の通りです。

フィールド	型	必須	仕様
`note_title`	string	○	ノートのタイトル (最大 100 文字)、空文字列は禁止
`note_content`	string	○	ノートの本文 (最大 5,000 文字)、空文字列は禁止

添付ファイルを追加したい場合は note_attachments を指定します。

robot.hear(/note$/, (res) => {
  res.send({
    note_title: 'タイトル',
    note_content: '本文',
    note_attachments: [
      { path: '/path/to/image.png', name: 'image.png' },
      { path: './scripts/ping.js' }
    ]
  });
});

note_attachments フィールドの仕様は以下の通りです。

フィールド	型	必須	仕様
`note_attachments`	object[]	×	「添付ファイルオブジェクト」の配列

「添付ファイルオブジェクト」の仕様は以下の通りです。

フィールド	型	必須	仕様
`path`	string	○	添付ファイルのパス
`name`	string	×	添付ファイルの名前、省略した場合は `basename(path)` になる
`type`	string	×	添付ファイルのコンテンツタイプ、省略した場合はファイル情報から推測した値になる

また onsend フィールドを指定することで、send により作成されたノートを受け取ることができます。

robot.hear(/note$/, (res) => {
  res.send({
    note_title: 'タイトル',
    note_content: 'コンテンツ',
    onsend: (sent) => {
      console.log(`note: ${sent.note}`);
    }
  });
});

ノートオブジェクト (上記における sent.note の note) のフィールドは以下の通りです。

フィールド	型	仕様
id	string	ノート ID
title	string	ノートのタイトル
contentType	string	ノートのコンテンツタイプ、従来のノートは `'text'`、スタイル付きのノートは `'xml'` となる
content	string	ノートの本文
attachments	object[]	添付済ファイルオブジェクト (※フィールド仕様は非公開) の配列、添付済ファイルが無い場合は空配列となる

スタイル付きノートの作成 #

note_content_type: 'xml' を指定するとスタイル付きノートを作成することができます。

robot.hear(/note$/, (res) => {
  res.send({
    note_title: 'タイトル',
    note_content_type: 'xml',
    note_content: '<note version="1" xmlns="http://ns.direct4b.com/note">本文</note>',
  });
});

note_content フィールドには XML で本文を指定します。XML の仕様は「スタイル付きノートの XML 仕様」を参照してください。

その他のフィールドについては「テキストノートの作成」と同じ仕様です。

ノートの取得 #

以下のコードは指定された id のノートオブジェクトを取得します。

const id = ... // 取得したいノートの ID 文字列

robot.direct.notes.get({ id })
  .then(result => console.log(result.note))
  .catch(error => console.error(error.message));

id に指定する値は、onsend で受け取ったノートオブジェクトの id フィールドや、「ノートメッセージの受信」の note_id フィールドから得られる値を指定します。

この API で取得されるノートオブジェクトの構造は、「ノートの作成」の onsend で受け取れるノートオブジェクトと同じです。

ノートの更新 #

基本となる更新方法 #

以下の API を利用することで、指定したノートを指定したフィールド値で更新します。

robot.direct.notes.update(note, { note_content: '新しい本文' })
  .then(result => console.log(result.note))
  .catch(error => console.error(error.message));

第一引数に指定する note は、onsend や robot.direct.notes.get で取得したノートオブジェクトです。

第二引数には、「ノートの作成」で説明したフィールドの中から、更新したいフィールドだけを指定してください。指定したフィールドに対応する箇所が更新されます。

ただし、ノートのコンテンツタイプを変更することはできません (例えば、テキストノートをスタイル付きノートに、スタイル付きノートをテキストノートに変更する、といったことはできません) 。そのため note_content_type を update に指定するとエラーになります。

添付ファイルの更新方法 #

第二引数のフィールドとして note_attachments を指定するとノートの添付ファイルが更新されます。指定しなければ既存の添付ファイルが維持されます。

添付ファイルを新しく追加したい場合は、以下のように既存の添付ファイル情報 (note.attachments) とともに、「ノートの作成」で説明した「添付ファイルオブジェクト」と同じ形式のオブジェクトを追加で指定します。

const newAttachments = [
  ...note.attachments,          // ← 既存の添付ファイル情報
  { path: '/path/to/new-file' } // ← 新しく追加する添付ファイル情報
];

robot.direct.notes.update(note, { note_attachments: newAttachments })
  .then(result => console.log(result.note))
  .catch(error => console.error(error.message));

既存の添付ファイルのうち、一部だけを残して他を削除したい場合は、上記 newAttachments の部分を以下のようにします。

const newAttachments = [
  note.attachments[0],          // ← 既存の添付ファイルのうち、一つ目だけを残す
  { path: '/path/to/new-file' } // ← 新しく追加する添付ファイル情報
];

更新処理のオプション指定 #

第三引数にはオプションを指定することができます。

const updates = { note_content: '新しい本文' };
const options = { notify_talk_members_of_update: false }; // ノートの更新をトークメンバーに通知したくない場合のオプション指定

robot.direct.notes.update(note, updates, options)
  .then(result => console.log(result.note))
  .catch(error => console.error(error.message));

オプションに指定できるフィールドは以下の通りです。

フィールド	型	仕様
`notify_talk_members_of_update`	boolean	トークメンバーにノートの更新を通知するかどうか。通知する場合は `true`、通知しない場合は `false` を指定する。デフォルト値は `true`。

第三引数を省略した場合は、各オプションフィールドにデフォルト値を指定したものとみなされます。

ノートの削除 #

指定した id のノートを削除します。id 値は「ノートの取得」と同じです。

robot.direct.notes.delete({ id: note.id })
  .then(_ => console.log('deleted'))
  .catch(error => console.error(error.message));

ノートメッセージの受信 #

direct でノートを作成・更新・削除すると、これらの操作を表すメッセージがトークに送信されます。これらのメッセージをボットで受け取りたい場合は以下のようにします。

// ノートが作成された
robot.hear('note_created', (res) => {
    const j = res.json;
    console.log(`created: id = ${j.note_id}, title = ${j.title}`);
});

// ノートが更新された
robot.hear('note_updated', (res) => {
    const j = res.json;
    console.log(`updated: id = ${j.note_id}, title = ${j.title}`);
});

// ノートが削除された
robot.hear('note_deleted', (res) => {
    const j = res.json;
    console.log(`deleted: id = ${j.note_id}, title = ${j.title}`);
});

補足: direct クライアントにおける「ノートの編集」で「変更をトークに通知する」のチェックを外すと、更新メッセージがトークに送信されません。この場合 note_updated ハンドラは反応しません。

res.json が持つフィールドは以下の通りです。

フィールド	型	仕様
`note_id`	string	ノート ID
`title`	string	ノートのタイトル

制限 #

robot.direct.notes 経由の API 呼び出しは「24 回/120 秒」に制限されています。