プリザンターAPIでセッション間のデータ共有を実現する方法

はじめに

サーバスクリプトでは context.UserData を使って、セッション間でデータを共有できることをご存知の方は多いと思います。実はこの機能、API経由でも同様のことが実現可能です。

今回は Sessions API を使って、ユーザーごとのデータ共有を行う方法を紹介します。

Sessions API とは

プリザンターには /api/sessions というAPIエンドポイントが用意されており、セッションデータの操作が可能です。

エンドポイント	メソッド	説明
/api/sessions/get	POST	セッション値を取得
/api/sessions/set	POST	セッション値を設定
/api/sessions/delete	POST	セッション値を削除

リクエストパラメータ

{
  "ApiKey": "your-api-key",
  "SessionKey": "キー名",
  "SessionValue": "値",
  "SavePerUser": true
}

パラメータ	型	必須	説明
ApiKey	string	Yes	APIキー
SessionKey	string	Yes	セッションのキー名
SessionValue	string	Set のみ	保存する値
SavePerUser	bool	No	true: ユーザー単位で保存（デフォルト: false）

SavePerUser の違い

値	保存先	用途
false	ブラウザセッション（SessionGuid）	一時的なデータ
true	ユーザーID	セッション間で共有するデータ（context.UserData 相当）

SavePerUser: true を指定すると、サーバスクリプトの context.UserData と同じユーザー単位の永続化領域にデータが保存されます。

context.UserData との機能対比

機能	context.UserData（サーバスクリプト）	Sessions API（SavePerUser: true）
データの取得	context.UserData.Key	/api/sessions/get
データの設定	context.UserData.Key = value	/api/sessions/set
データの削除	delete context.UserData.Key	/api/sessions/delete
保存先	ユーザーID単位	ユーザーID単位（同一領域）
呼び出し元	サーバスクリプト内のみ	外部システム・スクリプト
認証	プリザンターログイン	APIキー
データ型	任意（自動シリアライズ）	文字列（JSON文字列で複合データ可）
相互運用	API で設定した値を参照可能	サーバスクリプトで設定した値を参照可能

Sessions API と context.UserData は同じデータ領域を共有しているため、双方向でデータの読み書きが可能です。

使用例

セッション値の設定（Set）

curl -X POST "https://your-pleasanter/api/sessions/set" \
  -H "Content-Type: application/json" \
  -d '{
    "ApiKey": "your-api-key",
    "SessionKey": "LastAccessTime",
    "SessionValue": "2026-02-24T10:30:00",
    "SavePerUser": true
  }'

レスポンス:

{
  "StatusCode": 200,
  "Response": {
    "UserId": 1,
    "Key": "LastAccessTime"
  }
}

セッション値の取得（Get）

curl -X POST "https://your-pleasanter/api/sessions/get" \
  -H "Content-Type: application/json" \
  -d '{
    "ApiKey": "your-api-key",
    "SessionKey": "LastAccessTime",
    "SavePerUser": true
  }'

レスポンス:

{
  "StatusCode": 200,
  "Response": {
    "UserId": 1,
    "Key": "LastAccessTime",
    "Value": "2026-02-24T10:30:00"
  }
}

セッション値の削除（Delete）

curl -X POST "https://your-pleasanter/api/sessions/delete" \
  -H "Content-Type: application/json" \
  -d '{
    "ApiKey": "your-api-key",
    "SessionKey": "LastAccessTime",
    "SavePerUser": true
  }'

レスポンス:

{
  "StatusCode": 200,
  "Response": {
    "UserId": 1,
    "Key": "LastAccessTime"
  }
}

サーバスクリプトとの連携

API で設定したデータは、サーバスクリプトの context.UserData でも参照できます。

API で設定

curl -X POST "https://your-pleasanter/api/sessions/set" \
  -H "Content-Type: application/json" \
  -d '{
    "ApiKey": "your-api-key",
    "SessionKey": "ExternalSystemStatus",
    "SessionValue": "connected",
    "SavePerUser": true
  }'

サーバスクリプトで参照

// API で設定した値を取得
const status = context.UserData.ExternalSystemStatus;

if (status === 'connected') {
  // 外部システム連携済みの処理
}

逆に、サーバスクリプトで設定した値を API で取得することも可能です。

サーバスクリプトで設定

// ユーザーデータに保存
context.UserData.ProcessedAt = new Date().toISOString();

API で取得

curl -X POST "https://your-pleasanter/api/sessions/get" \
  -H "Content-Type: application/json" \
  -d '{
    "ApiKey": "your-api-key",
    "SessionKey": "ProcessedAt",
    "SavePerUser": true
  }'

活用シナリオ

1. 外部システムとの状態共有

外部システムからAPIでフラグを設定し、プリザンター側のサーバスクリプトで参照する。

# 外部システムから承認状態を設定
curl -X POST "https://your-pleasanter/api/sessions/set" \
  -d '{
    "ApiKey": "...",
    "SessionKey": "ApprovalStatus",
    "SessionValue": "{\"approved\": true, \"approvedAt\": \"2026-02-24\"}",
    "SavePerUser": true
  }'

2. バッチ処理の進捗管理

# バッチ処理の進捗を保存
curl -X POST "https://your-pleasanter/api/sessions/set" \
  -d '{
    "ApiKey": "...",
    "SessionKey": "BatchProgress",
    "SessionValue": "{\"total\": 100, \"processed\": 45}",
    "SavePerUser": true
  }'

3. ユーザー設定の外部管理

# ユーザーのカスタム設定を保存
curl -X POST "https://your-pleasanter/api/sessions/set" \
  -d '{
    "ApiKey": "...",
    "SessionKey": "UserPreferences",
    "SessionValue": "{\"theme\": \"dark\", \"pageSize\": 50}",
    "SavePerUser": true
  }'

注意事項

実装確認ベースのステータス条件

Pleasanter 本体実装（SessionsController / SessionUtilities）を確認すると、/api/sessions/get の 404 は「エンドポイントが存在しない」以外の条件でも返されます。

API	条件	ステータス	備考
Get	指定キーが存在しない	404	未登録キー。初回アクセス時に発生しうる
Delete	指定キーが存在しない	404	すでに削除済みを含む
Get/Set/Delete	Content-Type が API 要件外	400	application/json で送る
Get/Set/Delete	JSON 不正 / SessionKey 欠落	400	必須パラメータ不足
Get/Set/Delete	認証失敗（ApiKey 不正など）	401	リクエスト自体は到達している
Get/Set/Delete	IP 制限に抵触	403	AllowIpAddresses / 契約IP制限

Get の 404 は「データ未登録」を意味するケースがあるため、クライアント実装では「例外」ではなく「未保存の初期状態」として扱うのが安全です。

• SessionKey と SessionValue は必須パラメータです（Get/Delete では SessionValue は不要）
• 存在しないキーを取得しようとすると 404 NotFound が返されます
• API認証に失敗すると 401 Unauthorized が返されます

まとめ

Sessions API を使うことで、以下のことが実現できます：

• API経由でのセッションデータ操作
• サーバスクリプトの context.UserData との相互運用
• 外部システムとプリザンター間でのデータ共有

特に SavePerUser: true を指定することで、ブラウザセッションに依存しない、ユーザー単位のデータ永続化が可能になります。外部システム連携やバッチ処理との連携に活用してみてください。