next

イベントの概要

イベントモデル

イベント受付APIにて定義された外部イベント、およびPersonium内部で定義された内部イベントから構成されます。

イベントモデル

外部イベント

イベント受付API にて、受け付けるイベントを表します。
イベント受付APIによって受け付けたイベントは、イベントバスに出力されます。

内部イベント

Personium内部で保持する管理データ（OData/WebDAV/Service等）の状態をもとに実行される処理のことを表します。
代表的な内部イベントとして、Personium APIのリクエストがあり、Personium APIのレスポンス返却時に実行結果をイベントとしてイベントバスに出力します。

イベントフォーマット

イベントは以下の項目から構成されます。

項目名説明
SubjectAuthorizationヘッダのトークンにより設定されます
SchemaAuthorizationヘッダのトークンにより設定されます
RequestKeyX-Personium-RequestKeyヘッダにより設定されます
External外部イベントか内部イベントかを表します
Typeイベントのタイプを表します
Objectイベントの対象を表します
Infoイベントの情報を表します

内部イベント詳細

Typeは、操作に対して定義されています。 リンクおよびリンク解除では、エンティティ名の順序を昇順に正規化します。以下に例を示します。

正規化
cellctl.Role.links.Box.createcellctl.Box.links.Role.create
cellctl.Relation.links.ExtCell.deletecellctl.ExtCell.links.Relation.delete

Objectは、基本的には、URLもしくは、キーを含めたURLが設定されます。 URLは、personium-localcellスキームによるURLであり、キーを含めたURLは、作成後のキーを付与したURLになります。 例えば、__idが0123のentityを作成した場合、リクエストURLとキーを含めたURLは以下のようになります。

リクエストURLキーを含めたURL
http://cell1.unit1.example/box/col/entitypersonium-localcell:/box/col/entity('0123')

Objectにおけるキーは、正規化されています。正規化の例を以下に示します。

正規化
Role(’role’)Role(Name=’role’, _Box.Name=null)
Role(_Box.Name=null, Name=’role’)Role(Name=’role’, _Box.Name=null)
Account(Name=’hoge’)Account(’hoge’)

Infoは、基本的には、リクエストのレスポンスコードとリクエストURLが設定されます。リクエストURLは、リクエストされたときのURLであり、引数も含みます。 更新操作では、変更後のキーが設定されます。変更後のアクセス先を得るためにInfoに設定しています。

TypeObjectInfo
celctl.Role.updatepersonium-localcell:/__ctl/Role(Name='role1', _Box.Name=null)204,(Name='role2', _Box.Name=null)

変更後のオブジェクトにアクセスするには、変更後のキーを使用して以下のURLにする必要があります。

personium-localcell:/__ctl/Role(Name='role2', _Box.Name=null)

Cell Level API

Cell制御オブジェクト
操作TypeObjectInfo備考
基本操作作成cellctl.xxx.createキーを含めたURL201,リクエストURL
取得cellctl.xxx.getURL200,リクエストURL
一覧取得cellctl.xxx.listURL200,リクエストURL
更新cellctl.xxx.updateURL204,変更後のキー
削除cellctl.xxx.deleteURL204
他オブジェクトとのリンクリンクcellctl.xxx.links.yyy.createキーを含めたURL204
リンク解除cellctl.xxx.links.yyy.deleteURL204
リンク一覧取得cellctl.xxx.links.yyy.listURL200,リクエストURL
紐づく他オブジェクト操作作成cellctl.xxx.navprop.yyy.createキーを含めたURL201,リクエストURL
一覧取得cellctl.xxx.navprop.yyy.listURL200,リクエストURL

xxxやyyyには、Cell制御オブジェクト名が入ります。

  • Account
  • Role
  • ExtCell
  • Relation
  • ExtRole
  • Box
  • SentMessage
  • ReceivedMessage
  • Rule
アクセス制御
操作TypeObjectInfo備考
CellACL設定cell.aclpersonium-localcell:/200
プロパティ取得cell.propfindpersonium-localcell:/207
プロパティ変更cell.proppatchpersonium-localcell:/207
BoxACL設定box.aclURL200
プロパティ取得box.propfindURL207
プロパティ変更box.proppatchURL207
Boxインストール
状態TypeObjectInfo備考
Boxインストール受付boxinstallURL202などBoxインストールの受付が失敗するとInfoの値は変わります
Boxインストール処理中PL-BI-1000URLBar installation started.
PL-BI-1001Barファイル内のエントリパスInstallation started.
PL-BI-1003Barファイル内のエントリパスInstallation completed.
PL-BI-1004Barファイル内のエントリパスInstallation failed({原因}).
PL-BI-1005Unknown error({原因}).
Boxインストール完了PL-BI-0000URLBar installation completed.
PL-BI-0001URLBar installation failed({原因}).

BoxインストールによりCell制御オブジェクトの作成が実行されることがあります。そのイベントは以下になります。

操作TypeObjectInfo備考
基本操作作成cellctl.xxx.createキーを含めたURLbox install
他オブジェクトとのリンクリンクcellctl.xxx.links.yyy.createキーを含めたURLbox install
Box再帰削除
TypeObjectInfo備考
box.deleteURL204
Cell間のメッセージ交換
操作TypeObjectInfo備考
メッセージ送信送信message.send送信メッセージ取得用URL201
受信message.receive受信メッセージ取得用URL201メッセージを受信したCellにてイベント化
状態変更既読message.read受信メッセージ取得用URL204
未読message.unread受信メッセージ取得用URL204
承認message.approve受信メッセージ取得用URL204
拒否message.reject受信メッセージ取得用URL204

送信メッセージ取得用URLと受信メッセージ取得用URLの例を以下に示します。

URL
送信メッセージ取得用URLpersonium-localcell:/__ctl/SentMessage(’12345’)
受信メッセージ取得用URLpersonium-localcell:/__ctl/ReceivedMessage(’12345’)

メッセージ承認によりCell制御オブジェクトの作成と削除が実行されることがあります。そのイベントは以下になります。

操作TypeObjectInfo備考
基本操作作成cellctl.ExtCell.createキーを含めたURLapproved for message 1234512345はメッセージidです
作成cellctl.Rule.createキーを含めたURLapproved for message 1234512345はメッセージidです
削除cellctl.Rule.deleteURLapproved for message 1234512345はメッセージidです
他オブジェクトとのリンクリンクcellctl.ExtCell.links.Relation.createキーを含めたURLapproved for message 1234512345はメッセージidです
リンクcellctl.ExtCell.links.Role.createキーを含めたURLapproved for message 1234512345はメッセージidです
リンク解除cellctl.ExtCell.links.Relation.deleteURLapproved for message 1234512345はメッセージidです
リンク解除cellctl.ExtCell.links.Relation.deleteURLapproved for message 1234512345はメッセージidです
その他機能
操作TypeObjectInfo備考
エクスポート実行cell.exportpersonium-localcell:/__export
インポート実行cell.importpersonium-localcell:/__import

Box Level API

WebDAV基本操作
操作TypeObjectInfo備考
WebDav Collection作成webdavcol.mkcolURL201
ACL設定webdavcol.aclURL200
プロパティ取得webdavcol.propfindURL207
プロパティ変更webdavcol.proppatchURL207
削除webdavcol.deleteURL204
OData Service Collection作成odatacol.mkcolURL201
ACL設定odatacol.aclURL200
プロパティ取得odatacol.propfindURL207
プロパティ変更odatacol.proppatchURL207
削除odatacol.deleteURL204
Engine Service Collection作成servicecol.mkcolURL201
ACL設定servicecol.aclURL200
プロパティ取得servicecol.propfindURL207
プロパティ変更servicecol.proppatchURL207
削除servicecol.deleteURL204
Stream Collection作成streamcol.mkcolURL201
ACL設定streamcol.aclURL200
プロパティ取得streamcol.propfindURL207
プロパティ変更streamcol.proppatchURL207
削除streamcol.deleteURL204
ファイル登録davfile.createURL201
更新davfile.updateURL204
取得davfile.getURL200
ACL設定davfile.aclURL200
プロパティ取得davfile.propfindURL207
プロパティ変更davfile.proppatchURL207
削除davfile.deleteURL204
ODataサービスコレクション
データ操作
操作TypeObjectInfo備考
基本操作作成odata.createキーを含めたURL201,リクエストURL
取得odata.getURL200,リクエストURL
一覧取得odata.listURL200,リクエストURL
更新odata.updateURL204,変更後のキー
部分更新odata.patchURL204,変更後のキー
削除odata.deleteURL204
他EntitySetのEntityとのリンクリンクodata.links.createキーを含めたURL204
リンク解除odata.links.deleteURL204
リンク一覧取得odata.links.listURL200,リクエストURL
紐づく他EntitySet操作作成odata.navprop.createキーを含めたURL201,リクエストURL
一覧取得odata.navprop.listURL200,リクエストURL
スキーマ定義
操作TypeObjectInfo備考
基本操作作成odata.xxx.createキーを含めたURL201,リクエストURL
取得odata.xxx.getURL200,リクエストURL
一覧取得odata.xxx.listURL200,リクエストURL
更新odata.xxx.updateURL204,変更後のキー
部分更新odata.xxx.patchURL204,変更後のキー
削除odata.xxx.deleteURL204
EntityTypeや他のAssociationEndとのリンクリンクodata.xxx.links.yyy.createキーを含めたURL204
リンク解除odata.xxx.links.yyy.deleteURL204
リンク一覧取得odata.xxx.links.yyy.listURL200,リクエストURL

xxxやyyyには、スキーマ定義用EntitySet名が入ります。

Engineサービスコレクション
操作TypeObjectInfo備考
サービス実行service.execURL200などスクリプトの実行結果によりInfoの値は変わます

イベントの処理

イベントバスに出力されたイベントは、ルールの条件と合致するか判定され、合致した場合は、ルールに記述されたアクションを実行される。 アクションには、以下が指定可能。

  • ログ出力
  • スクリプト実行
  • 中継
  • イベント中継
  • データ中継

ルールとのマッチング

下記表の通りに項目毎に判定を行い、すべての項目が合致した場合に、ルールに合致したと判定する。

イベントルール判定備考
SubjectEventSubject完全一致EventSubjectがnullのときは合致と判定
Schema_Box.NameのBoxのSchema完全一致_Box.Nameがnullのときは合致と判定
RequestKey判定に使用しません
ExternalEventExternal完全一致
TypeEventType前方一致もしくは後方一致.で始まるEventTypeのときは後方一致で、それ以外は前方一致。
EventTypeがnullのときは合致と判定
ObjectEventObject前方一致EventObjectがnullのときは合致と判定
InfoEventInfo前方一致EventInfoがnullのときは合致と判定

ログ出力アクション

ログ出力アクションは、イベントの内容をイベントログとして出力します。 ログ出力アクションには、以下の種類があります。

アクション説明
log
log.info		INFOレベルでログを出力します
log.warnWARNレベルでログを出力します
log.errorERRORレベルでログを出力します

イベントにはログ出力レベルはなく、アクションにてレベルを指定します。

ルール例

Cell制御オブジェクトのRole操作をログ出力する例

項目名設定備考
_Box.Namenull
Nameoutput_cellctlRole設定しなくてもよいです
EventTypecellctl.Role.
EventSubjectnull
EventObjectpersonium-localcell:/__ctl/RoleEventTypeで限定されるので実際には冗長です
EventInfonull
EventExternalfalse
Actionlog
TargetUrlnull

Roleを操作するとログがINFOレベルで出力されます。

イベントログフォーマット

出力形式は以下の通り。

{dateTime},[{level}],{RequestKey},{External},{Schema},{Subject},{Type},{Object},{Info}

イベントログアクセス方法

イベントログは、WebDAV上で管理するため、イベントログファイルへのアクセスはWebDAV用のAPIで行う。

イベントログ保管期間

イベント量に応じてイベントログファイルのサイズが増大するため、一定量にてイベントログファイルをローテートする。
ローテートされたイベントログファイルの保持世代数は、最大12世代とする。
なお、ローテート時の最大サイズは、デフォルト50MBとし、ログ設定更新APIにて設定可能とする。

出力例

外部イベントの出力例
2013-04-18T14:52:39.778Z,[ERROR],"Req_animal-access_1001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","actionData",
"/svc/token_keeper","resultData"
2013-04-18T14:52:40.688Z,[INFO ],"Req_animal-access_2001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","action",
"/svc/token_keeper","result"
2013-04-18T15:01:46.994Z,[INFO ],"Req_animal-access_2001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","action",
"/svc/token_keeper","result"
2013-04-18T15:06:19.294Z,[ERROR],"Req_animal-access_1001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","actionData",
"/svc/token_keeper","resultData"
2013-04-18T15:06:23.360Z,[INFO ],"Req_animal-access_2001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","action",
"/svc/token_keeper","result"
2013-04-18T15:09:18.073Z,[ERROR],"Req_animal-access_1001","true",
"https://app-cell1.unit1.example/","https://unitadmin.unit1.example/#admin","actionData",
"/svc/token_keeper","resultData"
内部イベントの出力例
2013-04-18T14:52:39.779Z,[INFO ],"Req_animal-access_1001","false",
"https://app-cell1.unit1.example/","https://app-cell1.unit1.example/#staff","odata.update",
"https://homeClinic.unit1.example/box/col/put_blog","204"
2013-04-18T14:52:39.780Z,[INFO ],"Req_animal-access_1001","false",
"https://app-cell1.unit1.example/","https://app-cell1.unit1.example/#staff","odata.get",
"https://homeClinic.unit1.example/box/col/blog_20130418","200"

スクリプト実行アクション

スクリプト実行アクションは、イベントの内容を渡して自Cellのサービスを実行します。 アクションは、execです。

ルール例

メッセージ受信でサービスを実行する例

項目名設定備考
_Box.Namenull
Nameexec_messagereceive設定しなくてもよいです
EventTypemessage.receive
EventSubjectnull
EventObjectnull
EventInfonull
EventExternalfalse
Actionexec
TargetUrlpersonium-localcell:/box/col/srv

メッセージを受信したとき、TargetUrlのサービスが実行されます。サービスにて受信メッセージを確認して必要に応じて承認することができます。

サービスへのパラメータ

JSON形式のBodyとリクエストヘッダでイベントの内容を渡します。

項目名データソース備考
SubjectJSON
SchemaJSON
ExternalJSON
TypeJSON
ObjectJSONhttpやhttpsスキームに変換されたURL
InfoJSON
RequestKeyヘッダx-personium-requestkey

JSONは、サービス実行において、引数のinputフィールドから取得します。

function(request) {
  var bodyAsString = request["input"].readAll();
  var params = JSON.parse(bodyAsString);

ヘッダは、サービス実行において、引数のheadersフィールドから取得します。

function(request) {
  var reqHeaders = request["headers"];
  var requestKey = reqHeaders['x-personium-requestkey'];

スクリプト実行時のトークン

Authorizationヘッダにアクセストークンが設定されます。

項目名設定値
SubjectイベントのSubjectと同じ
SchemaイベントのSchemaと同じ

事前設定

スクリプトが実行できるように権限を設定しておく必要があります。

中継アクション

中継アクションは、イベントの内容を渡して他Cellのサービスを実行します。 アクションは、relayです。

ルール例

OData作成操作で中継する例

項目名設定備考
_Box.Namenull
Namerelay_odatacreate設定しなくてもよいです
EventTypeodata.create
EventSubjectnull
EventObjectpersonium-localcell:/box/odatacol/entity
EventInfonull
EventExternalfalse
Actionrelay
TargetUrlpersonium-localunit:/otherCell/box/col/srv

TypeおよびObjectが合致する内部イベントのとき、TargetUrlへイベントを中継します。

スクリプトへのパラメータ

スクリプト実行アクションと同じです。

スクリプト実行時のトークン

Authorizationヘッダには、サービスを実行するためにトランスセルトークンが設定されています。

項目名設定値
SubjectイベントのSubjectと同じ
SchemaイベントのSchemaと同じ

事前設定

スクリプトが実行できるように権限を設定しておく必要があります。

イベント中継アクション

イベント中継アクションは、イベントの内容を他Cellの外部イベント受付に中継します。 アクションは、relay.eventです。

ルール例

外部イベント受付で中継する例

項目名設定備考
_Box.Namenull
Namerelayevent_eventreceipt設定しなくてもよいです
EventTypenull
EventSubjecthttps://cell1.unit1.example/#account
EventObjectnull
EventInfonull
EventExternaltrue
Actionrelay.event
TargetUrlhttps://cell2.unit1.example/

Subjectが合致する外部イベントのとき、イベント中継を行います。

リクエスト

リクエストヘッダ
ヘッダ名設定値備考
X-Personium-RequestKeyイベントのRequestKey
Authorizationトランスセルトークン
イベントのSubjcetとSchemaを設定
中継元のRoleリストを設定
リクエストボディ
項目名設定値備考
Type以下の表のように変換された値
ObjectイベントのObject
InfoイベントのInfo

Typeの変換

ExternalType
truerelay.ext. を先頭に追加
falserelay. を先頭に追加

既にTypeがrelay.で始まっていれば、Typeの変換は行われません。

イベント中継によるイベント伝播の例

cell1で起きたイベントをcell2を経由してcell3にイベント中継する例

内部イベントの場合
ルール
項目名cell1cell2
_Box.Namenullnull
Namerelayeventrelayevent
EventTypecellctlnull
EventSubjectnullhttps://cell1.unit1.example/#account
EventObjectnullnull
EventInfonullnull
EventExternalfalsetrue
Actionrelay.eventrelay.event
TargetUrlhttps://cell2.unit1.example/https://cell3.unit1.example/
伝播されるイベント
項目名cell1cell2cell3
Subjecthttps://cell1.unit1.example/#account<-<-
Schemahttps://app-cell1.unit1.example/<-<-
Externalfalsetruetrue
Typecellctl.Role.createrelay.cellctl.Role.create<-
Objecthttps://cell1.unit1.example/__ctl/Role('role')<-<-
Info201,https://cell1.unit1.example/__ctl/Role<-<-
外部イベントの場合
ルール
項目名cell1cell2
_Box.Namenullbox2
Namerelayeventrelayevent
EventTypenullnull
EventSubjectnullhttps://cell1.unit1.example/#account
EventObjectobjectnull
EventInfonullnull
EventExternaltruetrue
Actionrelay.eventrelay.event
TargetUrlhttps://cell2.unit2.example/https://cell3.unit3.example/

cell2のbox2のSchemaは、https://app-cell1.unit1.example/とします。

伝播されるイベント
項目名cell1cell2cell3
Subjecthttps://cell1.unit1.example/#account<-<-
Schemahttps://app-cell1.unit1.example/<-<-
Externaltruetruetrue
Typetyperelay.ext.type<-
Objectobject<-<-
Infoinfo<-<-

事前設定

外部イベント受付へのアクセスに必要な権限を設定しておく必要があります。

データ中継アクション

データ中継アクションは、ODataとして書き込まれた内容をTargetUrlに書き込みます。 アクションは、relay.dataです。

イベントのTypeがodata.createのときは、TargetUrlにPOSTし、イベントのTypeがodata.update、odata.patchのときは、TargetUrlにPUTします。 PUTのときの{EntityID}は、イベントのObjectの{EntityID}を使用します。

ルール例

OData作成操作でデータ中継する例

項目名設定備考
_Box.Namenull
Namerelaydata_odatacreate設定しなくてもよいです
EventTypeodata.create
EventSubjectnull
EventObjectpersonium-localcell:/box/odatacol/entity
EventInfonull
EventExternalfalse
Actionrelay.data
TargetUrlpersonium-localunit:/otherCell/box/col/queue/name

TypeおよびObjectが合致する内部イベントのとき、ODataとして書かれた内容をTargetUrlへ書き込みます。

TargetUrlへのパラメータ

ODataのレスポンスのresultsから、__metadata、__published、__updatedを削除したJSON Stringを渡します。__idは、JSON Stringに含まれます。

PUT時のTargetUrlは、イベントのObjectが以下であった場合、

    personium-localcell:/box/odatacol/entity('id1')

上記ルール例では、

    personium-localunit:/otherCell/box/col/queue/name('id1')

としてアクセスを行います。

TargetUrlへのトークン

Authorizationヘッダには、アクセストークンもしくはトランスセルトークンが設定されています。

項目名設定値
SubjectイベントのSubjectと同じ
SchemaイベントのSchemaと同じ

事前設定

ODataのread権限、およびTargetUrlへの書き込み権限(writeやstream-send)を設定しておく必要があります。

← ReceivedMessage削除外部イベント受付 →