intdash APIのリソース
intdashが持つ主要なリソースとして「ユーザー」「エッジ」「データポイント」「計測」があります。その他の細かなリソースは、これらの主要リソースと関連付けて理解することができます。まずは主要リソースの概要について説明します。
- ユーザー（User）
「ユーザー」は、intdashにアクセスする人に対応するリソースです（詳細）。ユーザー名やパスワードを情報として持ち、UIアプリケーションへログインする場合にそれらの情報を使用します。
- エッジ（Edge）
「エッジ」は、intdashとデータをやり取りするノードを表すリソースです（詳細）。intdashは、ある場所で発生したデータを、サーバーに回収して保存したり、ほかの場所へ中継したりするミドルウェアです。この「ある場所」からデータを取得したり、「ほかの場所」でデータを受け取ったりするノードが「エッジ」です。
- データポイント（Data Points）
「エッジ」が取得したデータは、発生した時刻や取得した時刻などの時刻情報を付与されることで、時間軸上のある一点に紐付けられます。この時間軸上の1点に紐付けられたデータを「データポイント」と呼びます（詳細）。
- 計測（Measurement）
「エッジ」が時間とともにデータを取得することで、時間軸上に複数の「データポイント」が生成されていきます。ある「エッジ」が、ある期間に生成した複数の「データポイント」の一連のまとまりを、intdashでは「計測」と呼びます（詳細）。「計測」は、そのデータを生成した「エッジ」に紐付けられます。
ユーザー（User）
前述の通り、「ユーザー」は、intdashにアクセスする人に対応するリソースです。
ユーザーが持つ属性
ユーザーは、以下のような属性を情報として持ちます（抜粋）。
ユーザー名
ニックネーム
メールアドレス（複数）
ロール
パスワード
APIトークン
ユーザーの認証情報
ユーザーは、以下のいくつかの認証情報を持ちます。
ユーザー名とパスワード
APIトークン
OAuth2クライアント
ユーザー名とパスワードは、UIアプリケーションへサインインする際に使用します。APIトークンは、SDKなどからAPIアクセスを行う際に使用します。OAuth2クライアントは、intdashにアクセスするアプリケーションなどを作成した際に、アプリケーションに埋め込む認証情報として使用します。APIトークンとOAuth2クライアントは、1ユーザーにつき複数所有することができます。
ユーザーに関連する主な機能
これらの情報を利用して、以下のような機能が用意されています。
- パスワードリセット機能
パスワードを忘れた場合には、パスワードリセットメールによるパスワードリセット機能を使用することができます。パスワードリセットメールを送信するには、事前にメールアドレスが有効であることを検証しておく必要があります。
- パスワードロック機能
パスワードを所定の回数間違えるとパスワードがロックされるパスワードロック機能があります。パスワードがロックされた場合は、権限のあるユーザーはAPIからロックを解除することができます。
- ユーザーの有効化/無効化
パスワードロック以外に、一時的にユーザーを利用できなくする有効化/無効化機能があります。無効化されたユーザーは認証ができなくなり、intdashを利用できなくなります。
- 仮パスワードと本パスワード
パスワードには仮パスワードと本パスワードの2種類があります。仮パスワードは、例えば管理者がほかのユーザーのアカウントを代理登録し、ユーザー本人があとでパスワードを設定するような場合に使用します。管理者は一度仮のパスワードを発行し、ユーザーに本パスワードを設定するように促すことができます。仮パスワードには有効期限があります。
- ユーザーの権限を表すロール
ユーザーは、そのユーザーが操作できる範囲を示す「ロール」を情報として持ちます。ロールごとに操作できるエンドポイントが決められており、付与されたロールによって操作できる範囲が決まります。基本的には、「管理者（admin）」ロールと「一般メンバー（member）」ロールが存在し、管理者ロールのユーザーはintdashの環境全体に影響を与える管理操作が可能です。一方、一般メンバーロールのユーザーは、管理操作は許可されず、アプリケーションを利用するための最低限の権限が許可されます。
管理者よりも上位の権限をもつユーザーとして、「スーパーユーザー」が存在します。スーパーユーザーは、そのintdash環境の基盤を運用している人のためのアカウントで、すべての機能にアクセスすることができます。
- ユーザーによるエッジの所有
ユーザーは、エッジを所有することができます。管理者ロールのユーザーはすべてのエッジの設定を変更することができますが、一般メンバーロールのユーザー変更できるのは、自分が所有しているエッジの設定に限定されます。
エッジ（Edge）
前述の通り、「エッジ」は、intdash とデータをやり取りするノードを表すリソースです。
エッジが持つ属性
エッジ名
ニックネーム
所有者
クライアントシークレット
エッジの認証情報
エッジは、それ自体がOAuth2クライアントであり、OAuth2のクライアントIDとクライアントシークレットを持っているため、intdashサーバーにアクセスする際にクライアントクレデンシャルフローを使用することができます。 方法については エッジのOAuth2クライアントクレデンシャルを使う を参照してください。
ユーザーとは異なり、これ以外の認証情報（パスワードなど）は持ちません。
OAuth2のクライアントIDとしては、エッジのUUIDを使用します。 クライアントシークレットは、エッジを作成した際にレスポンスとして返却されます（再取得する方法はありません）。
データポイント（Data Point）
前述の通り、時間軸上の1点に紐付けられたデータが「データポイント」です。
データポイントの構造
データポイントは、時刻情報と、データ本体を格納したバイナリ（ペイロード）から構成されます。また、ペイロードの型情報を表すデータタイプと、データの意味を表すデータIDやチャンネルといったメタ情報を持ちます。時刻情報は、計測が持つ基準時刻からの相対時間（経過時間）の形式を取ります。
データポイントの保存方法
データポイントは、上り方向のリアルタイム伝送時、サーバーが受信した際に保存されます。別の方法として、データポイントの保存用APIを用いて、明示的に保存することもできます。
リアルタイム伝送時にデータポイントを保存するには、iSCPを用いて上り伝送を行い、iSCPのプロトコルに沿って、データポイントの保存をブローカーに指示します。保存用APIによる保存は、SDK等から直接データを保存する場合や、リアルタイム伝送でデータを送りきれなかった場合の再送時などで使用します。
データポイントと計測の関係
同じエッジが取得し送信した複数のデータポイントは、ある一連のまとまりごとにひとまとめにして、計測に紐付けられます。計測は基準時刻を持ち、データポイントはその基準時刻からの相対時間（経過時間）の形式で時刻情報を持ちます。よって、計測は、あるエッジが取得した、基準時刻を共有するデータポイントのまとまりと言うことができます。
計測（Measurement）
前述の通り、計測は、あるエッジが取得した、基準時刻を共有するデータポイントのまとまりです。
計測の削除
計測は取得したデータポイントを含み、ユーザーにとって重要なデジタル資産です。誤って削除してしまうことを防ぐため、計測の削除には段階を設けています。まず最初のステップでは、計測をゴミ箱に移動します。ゴミ箱に移動された計測は、その後、一定の時間（サーバーアプリケーションの設定による）が経過すると、完全に削除されます。完全に削除されるまでの間であれば、ゴミ箱から計測を復元することができます。
計測の基準時刻
計測に含まれるデータポイントは、基準となる時刻（基準時刻）からの相対時間（経過時間）の形式で、その時刻が管理されます。基準時刻は計測に紐付けられます。各データポイントの時刻を絶対時刻の時間軸上で表現したい場合は、そのデータポイントが所属する計測の基準時刻と、そのデータポイントが持つ経過時間から算出することで、絶対時刻を得ることができます。
基準時刻は、計測に複数紐付けることができます。NTPやGPSなどの絶対時刻の取得リソースごとに別々の基準時刻を紐付けることが想定されています。紐付けられた複数の基準時刻のうち、どの基準時刻をその計測の基準時刻として採用するかは、計測リソースが情報として保持しています。
計測のステータス
intdash は、リアルタイムでデータを伝送したあと、リアルタイム伝送時に送信しきれなかったデータを再送という形でサーバーへ回収します。データの伝送や回収がどのような状態かによって、計測は以下のステータスを取ります。
ready: 計測リソースは作成されたが、まだリアルタイム伝送（計測）が開始されていない
measuring: 計測をしている
resending: 計測は終了したが、リアルタイム伝送で送れなかったデータを回収中
finished: 計測は終了しており、データの回収も終わっている
計測の保護
計測のゴミ箱機能が追加されるまでの旧機能として、計測を削除から保護（protect）する機能がありました。保護された計測は、保護解除（unprotect）するまで削除ができません。ゴミ箱機能が追加されたことにより計測は即時削除されることはなくなったため、計測の保護機能は非推奨となる予定です。
計測マーカー
計測マーカーは、計測内の時刻一点もしくは時間範囲に印付けをするものです。計測マーカーには、名前をつけたり、キーバリューから成るタグを付与したりできます。計測マーカーもデータポイントと同様に計測の基準時刻からの経過時間によって計測と紐付けられるため、計測の基準時刻が変更された場合は、基準時刻と経過時間から算出される計測マーカーの絶対時刻も変更になります。
計測シーケンス
計測に含まれるデータポイントは計測シーケンスという単位でグルーピングされます。
リアルタイム伝送（アップストリーム）により計測が作成される場合、1つのストリームが1つの計測シーケンスとなります。
各計測シーケンスは、そのシーケンスに所属すべきデータポイント数の情報を持っています。また、すでにサーバーが受信したデータポイント数を内部的に持っています。 上記の2つの数値から、サーバー側で現在どれだけのデータが回収済みかが算出されます。
CSVファイルアップロードによる計測の作成
計測は、リアルタイム伝送されたデータがサーバーに保存されることにより作成されたり、計測の作成APIにより作成されたりする他に、CSVファイルのアップロードによっても作成されます。CSVファイルをアップロードすると、アップロードしたCSVファイルから計測を作成するジョブ（計測ジョブ）が作られ、非同期で実行されます。
信号定義（Signal）
信号定義とは、intdashサーバー上でバイナリデータから値を取り出すための定義です。 バイナリデータの指定された位置から指定されたビットサイズで固定小数点数として読み出したり、JSONデータから特定のフィールドの値を取り出したりできます。
信号定義はラベル(label)と呼ばれる名前を持っています。ダウンストリーム時にはこれをデータIDの代わりに指定することで、信号定義により変換された結果の値をダウンストリームで伝送することができます。
動画（Video）
動画リソースは、計測に含まれる動画関連のデータポイント群（JPEG、H.264など）を、intdash以外のツールで扱いやすい形式に変換したものです。 動画リソースは、HLS形式に変換されたストリーミング動画の取得エンドポイントを持ちます。動画リソースからHLSのプレイリストを取得することで、ストリーミング再生ができます。
計測に含まれる動画関連のデータポイント群をHLS形式に変換したり、変換されたHLS形式のデータを削除したりする処理は、ジョブとして非同期に実行されます。
また、動画からは、フレームごとに画像に切り出したJPEGファイルや、MP4形式の動画ファイルを生成することができます。
図 3 計測、動画、JPEG、MP4の関係