Personium API リファレンス

API リファレンスへようこそ。 ここではPersoniumが提供するすべてのAPIに関する技術的な詳細仕様を記述しています。 本リファレンス内のリクエストURLの変数についてはリクエストURLの変数一覧を参照してください。

Unit Level API

Unit Level API はCell群をホストするUnitに属するAPIで、Cellの生成や作成したCell群の管理を行うものです。
これらAPIは原則としてCellから発行されたアクセストークンではアクセスできず、Unitユーザとしてのトークンでのみアクセス可能です。

Unit Root URL

https://{UnitFQDN}/

Unit Level API の大半はUnit制御オブジェクトという形で実現されています。ODataに従ったREST操作でUnit制御オブジェクトを操作してください。

Unit制御オブジェクト

Cell	操作
基本操作	作成     取得     一覧取得     更新     削除

その他API

• Unitメタデータ取得
• Cell再帰削除

Cell Level API

Cell Level API は、Cellを管理するユーザがアプリ等を通じて操作するAPIで、以下のCellルートURL以下に展開されています。

Cell Root URL

{CellURL}

Cell Level API は、次のような機能で構成されます。

• 人やアプリケーションの認証
• アクセス制御
• Cell間の関係の構築
• Boxの生成・管理
• Cell間のメッセージ交換
• イベント処理
• その他機能

これら機能群の多くはCell制御オブジェクトという形で実現されています。Cell制御オブジェクトはODataに従ったREST操作で操作可能です。

人やアプリケーションの認証

認証

• OAuth2.0 認可エンドポイント
• OAuth2.0 トークンエンドポイント
• パスワード変更
• OAuth2.0 Token Introspection
• Cell公開鍵取得

Account (Cell制御オブジェクト)

Account	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

アクセス制御

• ACL設定
• プロパティ取得
• プロパティ変更

Role (Cell制御オブジェクト)

Role	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

Cell間の関係構築

ExtCell (Cell制御オブジェクト)

関係のある他のCellを登録管理するためのオブジェクトです。ExtCellとRoleをリンクさせることにより、そのCellで認証されたユーザに対し指定のロールを割り当てることができます。

ExtCell	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

Relation (Cell制御オブジェクト)

自Cellから見た外部Cellへの関係を表します。RelationをExtCellとリンクさせることにより、外部Cellとの関係を定義することができます。 また、RelationとRoleをリンクさせることにより、その関係で結ばれたCellで認証されたユーザに対し指定のロールを割り当てることができます。

Relation	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

ExtRole (Cell制御オブジェクト)

ある関係で結ばれた他のCellであるロールを得ているユーザを表します。これとRoleをリンクさせることにより、そのようなユーザに指定のロールを割り当てることができます。

ExtRole	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作作	作成     一覧取得

Boxの作成・管理

• Boxエクスポート
• Boxインストール
• Boxメタデータ取得
• URL取得
• 再帰削除

Box (Cell制御オブジェクト)

Box	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

Cell間のメッセージ交換

• メッセージ送信
• 状態変更 (承認・拒否等)

Cell制御オブジェクト	操作
送信済メッセージ	取得     一覧取得     削除
受信メッセージ	取得     一覧取得     削除

イベント処理

• イベントの概要
• 外部イベント受付
• イベントバスへの Web Socket 接続

イベント制御ルール　（Cell制御オブジェクト）

イベントが発生したときに起動すべき処理を記述することができます。フィルタすべきイベントの条件とその際に起動すべき処理を記述します。記述可能な処理は、ログ出力、engineスクリプトの起動、他URLへのイベント情報やデータのリレーです。

Rule	操作
基本操作	作成     取得     一覧取得     更新     削除
他オブジェクトとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他オブジェクト操作	作成     一覧取得

• Rule内部情報一覧取得

イベントログ操作

• ログファイル取得
• ログファイル一覧取得
• ログファイル情報取得
• ログファイル削除

その他機能

Cellルートアクセス

• Cellルート取得
• Cellメタデータ取得

エクスポート/インポートする機能

エクスポート実行でCellのスナップショットファイルが作成されます。
インポート実行でスナップショットファイルの内容をCellに取り込みます。
スナップショットファイルはWebDAVのインターフェースで操作可能です。

	操作
エクスポート	実行     状態取得
インポート	実行     状態取得
スナップショット	登録更新     取得     属性取得     削除

Box Level API

Box Level API は、アプリケーション等がデータを操作するためのAPIで、以下のBox ルートURL以下に展開されています。

Box Root URL

{CellURL}{BoxName}/

WebDAVをベースとしたファイルシステム的な考え方のAPI群で、通常のファイルシステムと同様にファイルの配置・取得、フォルダ（Collection）の作成・管理、ファイルやフォルダの一覧取得、アクセス制御の設定・参照等が可能です。

また以下の特殊コレクションをサポートしているため、ファイル状のデータのみではなく、様々な形態のデータを扱うことができます。 これら特殊コレクションはBoxが提供するWebDAV空間上のいかなるパスに作成することもできます。

特殊コレクション	用途	備考
OData Service Collection	リレーショナルデータ
Engine Service Collection	カスタマイズロジックの走行
Stream Collection	データをストリームとして扱う
CALDAV Collection	カレンダーデータ	未実装
Link Collection	他のCellや他Boxの特定の領域へのエイリアス	未実装

WebDAV 基本操作

対象	操作
コレクション	作成     設定取得     設定変更     移動名称変更     削除
ファイル	登録更新     取得     設定取得     設定変更     削除
共通	アクセス制御設定

※ すべてのファイルやコレクション（特殊コレクションを含む）に対してACL設定(アクセス制御設定)が可能です。
※ ACL設定 は PROPFINDメソッドで取得できます。

OData サービスコレクション

リレーショナルデータを扱うための特殊コレクションで、コレクション作成操作時に特定のパラメタを与えることにより作成可能です。スキーマ定義操作として、いわゆるテーブルに相当するEntityTypeを定義することで、その中にテーブル状のデータを格納・管理することができます。

スキーマ情報取得

	操作
スキーマ情報確認	ATOM サービスドキュメント取得     EDMX スキーマ取得

スキーマ定義

OData Service Collection には、スキーマ定義のためのOData Serviceが内包されています。この内包されたもうひとつのOData Service 上の Entity Set を操作することで、OData Service Collection の Entity Set やその中で扱うべき Property、Complex Propertyを定義したり、Entity Set 間の Association　を定義することができます。

スキーマ定義用 OData Service URL

{ODataServiceURL}/$metadata/

スキーマ定義用 Entity Set

EntityType	操作
基本操作	作成     取得     一覧取得     更新     削除

Property	操作
基本操作	作成     取得     一覧取得     更新     削除

AssociationEnd	操作
基本操作	作成     取得     一覧取得     更新     削除
EntityTypeや他のAssociationEndとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。

ComplexType	操作
基本操作	作成     取得     一覧取得     更新     削除

ComplexTypeProperty	操作
基本操作	作成     取得     一覧取得     更新     削除

データ操作

スキーマ定義でEntityTypeを定義すると対応するEntitySetが利用可能となります。

ユーザ定義EntitySet	操作
基本操作	作成     取得     一覧取得     更新     部分更新     削除
他EntitySetのEntityとのリンク	リンク     リンク解除     リンク一覧取得 リンク更新はありません。更新したい場合は削除して再作成してください。
紐づく他EntitySet操作	作成     一覧取得

一括操作

複数のオペレーションを一つのRESTリクエストにまとめて発行する機能です。アプリの性能確保のためには非常に重要なものです。

Engine サービスコレクション

PersoniumアプリケーションやCell利用者が作成したサーバサイドロジックを登録しこれを走行させることができます。 はじめに、ユーザロジックをファイルとして登録し、サービスコレクションの設定を行ってパスとの関連付けを行うことで、コレクション配下の任意のパスからのリクエストに対してユーザロジックを走行させることができます。

	操作
スクリプトファイル	作成     取得     削除
設定/実行	設定適用     サービス実行

Stream コレクション

メッセージキューとの送受信を行うことを可能にするコレクションです。メッセージキューの送受信に使うqueueやtopicを設定することで、設定したqueueに対する送受信やtopicに対する送信が可能になります。topicの受信は、WebSocket接続により可能です。

	操作	送信・受信
Streamコレクション	設定変更     OPTIONS	送信     受信     WebSocket接続

共通情報

• エラーメッセージ一覧
• PersoniumのHTTP実装に関する制限事項
• CORS対応
• クロスドメインポリシーファイル取得

OData取得共通クエリ

クエリ	一件取得使用可	一覧取得使用可
$formatクエリ	○	○
$expandクエリ	○	○
$selectクエリ	○	○
$orderbyクエリ	×	○
$topクエリ	×	○
$skipクエリ	×	○
$filterクエリ	×	○
$inlinecount	×	○
全文検索(q)クエリ	×	○