はじめに
Related information
概要
REST データサービスを使用すると、外部システムは、RESTful ビルトインサービスを使用して TIBCO EBX® リポジトリで管理されているデータと対話できます。
ビルトインサービスの要求と応答の構文については、ビルトイン RESTful サービスの章で説明しています。
ビルトイン REST データサービスにより、次のような操作を実行できます。
-
レコードの選択、挿入、更新、削除、またはカウント
-
履歴レコードの選択またはカウント
-
データセット値の選択、更新、またはカウント
-
データスペースまたはスナップショット情報の選択または更新
-
子データスペースまたはスナップショットの選択
-
データスペースの作成、マージ、またはクローズ
-
スナップショットの作成または終了
-
UI またはシステム情報へのアクセスを管理するための管理操作
注意:
SOAP と REST の比較を参照してください。
アクティベーションと構成
REST および SOAP データサービスは、
ebx-dataservices Web アプリケーションを他の EBX® モジュールと一緒に展開することでアクティブ化されます。詳細については、Java EE 展開を参照してください。
リバースプロキシモードを使用するなど、特定の展開の場合、詳細については、URL コンピューティングを参照してください。
HTTP(S) プロトコルのみがサポートされています。
インタラクション
ボディメディアタイプ
REST ビルトインの入力メッセージと出力メッセージは、排他的に UTF-8 エンコードを使用した JSON 形式である必要があります。ただし、入力メッセージを使用して HTML フォームデータを渡すこともできます。
詳細については、Content-Type を参照してください。
追跡情報
呼び出されるデータサービス操作によっては、セッション追跡情報を指定できる場合があります。
-
RESTful 操作の例として、拡張 JSON 形式のリクエストには次のものが含まれます。
{
"procedureContext": // JSON Object (optional)
{
"trackingInformation": "String" // JSON String (optional)
},
...
}詳細については、Java API のSession.getTrackingInfoを参照してください。
セッションパラメーター
呼び出されるデータサービス操作に応じて、セッション入力パラメーターを指定できます。それらはリクエスト本文で定義されます。
入力パラメーターは、トリガー、アクセスルール、
カスタム Web サービスなどのセッションオブジェクトを使用するカスタム Java コンポーネントで使用できます。これらは、データワークフロー操作でも使用できます。
-
RESTful 操作の例として、拡張 JSON 形式のリクエストには次のものが含まれます。
{
"procedureContext": // JSON Object (optional)
{
"trackingInformation": "String", // JSON String (optional)
"inputParameters": // JSON Array (optional)
[
// JSON Object for each parameter
{
"name": "String", // JSON String (required)
"value": "String" // JSON String (optional)
},
...
]
},
...
}詳細については、Java API のSession.getInputParameterValueを参照してください。
セッションチャネル
セッションチャネルを使用すると、REST ビルトインまたは REST Toolkit サービスを使用するときに、EBX® リポジトリから選択または変更できるものをフィルタリングできます。フィルターは、デフォルトビューを指定することにより、データモデルを通じて可視性が定義されるテーブル、グループ、またはフィールドの構成に基づいています。
これは、クエリパラメーター ebx-channel を介して指定できます。使用可能な値は次のとおりです。
-
dataServices -
ui
フィルターの動作は、次の組み合わせで説明されています。
データサービスチャネル
| XML エレメント | 値 | スキーマノードタイプ | ビュー | 動作 |
|---|---|---|---|---|
<hiddenInDataservices> |
true |
フィールドノード |
デフォルトの表形式のビュー | コンテンツのために非表示。ソート不可 |
| CustomView (表形式または階層形式) | メタ、コンテンツ、フィルター、並べ替えのために非表示 | |||
| デフォルトのフォームレコード | メタとコンテンツのために非表示 | |||
| デフォルトのフォームレコードフィールド | 見つかりません |
ユーザーインターフェイスチャネル
| XML エレメント | 値 | スキーマノードタイプ | ビュー | 動作 |
|---|---|---|---|---|
| <hidden> | true | テーブルノード | ツリービュー | メタとコンテンツのために非表示 |
| デフォルトの表形式のビュー | 見つかりません | |||
| CustomView (表形式または階層形式) | 禁止 | |||
| デフォルトのフォームレコード | 見つかりません | |||
| デフォルトのフォームレコードフィールド | ||||
| カスタムフォームレコード | ||||
| フィールドノード | デフォルトの表形式のビュー | コンテンツのために非表示。ソート不可 | ||
| デフォルトのフォームレコード | コンテンツのために非表示 | |||
| デフォルトのフォームレコードフィールド | 見つかりません | |||
| <hiddenInViews> | true | フィールドノード | CustomView (表形式または階層形式) | メタ、コンテンツ、フィルター、およびソートで非表示 |
| カスタムフォームレコード | メタとコンテンツのために非表示 | |||
| <hiddenInSearch> | true | フィールドノード | デフォルトの表形式のビュー | フィルタリングできません |
| CustomView (表形式または階層形式) | ||||
| デフォルトのフォームレコード | ||||
| デフォルトのフォームレコードフィールド | ||||
| カスタムフォームレコード | ||||
| textSearchOnly | デフォルトの表形式のビュー | テキスト検索以外はフィルタリングできません | ||
| CustomView (表形式または階層形式) | ||||
| デフォルトのフォームレコード | ||||
| デフォルトのフォームレコードフィールド | ||||
| カスタムフォームレコード |
注意:
上記のフィールドノードは、テーブルノードの下にのみ配置できます。
プロシージャのコンテキスト
呼び出されるデータサービス操作によっては、デフォルトのプロシージャコンテキスト設定を上書きすることができます。これらはリクエスト本文で定義され、ビルトインの操作内で適用されます。
プロシージャコンテキストは、カスタム REST Toolkit サービスに適用できます。
-
RESTful 操作の例として、JSON リクエストの本文には次のものが含まれています。
{
"procedureContext": // JSON Object (optional)
{
"commitThreshold": Integer // JSON Number (optional)
},
...
}
詳細については、Java APIの
ProcedureContext.setCommitThreshold、SessionContext.getProcedureUtility、およびProcedureUtility.execute を参照してください。
例外処理
エラーが発生すると、JSON 例外応答が呼び出し元に返されます。ほとんどの場合、例外は REST Toolkit のような JSON 形式を取ります。
以下も参照してください。:
{
"code": 999, // JSON Number, HTTP error code or EBX® error code
// in case of HTTP error 422 (optional)
"errors": [ // Additional messages to give details (optional).
{
"message": "Message 1" // JSON String
},
{
"message": "Message 2"
}
]
}
複数のレコードの挿入または更新中にエラーが発生した場合、エラーレポートが返されます。
{
"code": 999, // JSON Number, HTTP status code
"errors": [
{
"level": "...", // JSON String, severity level (optional)
"rowIndex": 999, // JSON Number, request row index (optional)
"userCode": "...", // JSON String, user code (optional)
"message": "...", // JSON String, message
"blocksCommit": "...", // JSON String, Type of blocking constraints (optional)
"details": "...", // JSON String, URL (optional)
"pathInRecord": "...", // JSON String, Path in record (optional)
"pathInDataset": "..." // JSON String, Path in dataset (optional)
}
]
}
応答には、HTTP ステータスコードとエラーのテーブルが含まれています。各エラーの重大度は、可能な値 (
fatal、 error、 warning、 info) のいずれかを使用して文字で指定されます)。
HTTP エラー
422 (処理不能エンティティ) は機能エラーに対応します。 userCode キーの下にユーザーコードが含まれ、JSON String タイプです。
以下も参照してください。:
セキュリティ
認証
コンテンツへのアクセスには認証が必須です。いくつかの認証方法が利用可能で、以下で説明されています。説明は優先度順に並べられています (EBX® は最も優先度の高い認証方式を最初に適用します)。
-
「トークン認証スキーム」方式は、
RFC 2617で説明されているように、HTTP ヘッダー承認に基づいています。
> Authorization: <tokenType> <accessToken>この認証スキームの詳細については、トークン認証操作を参照してください。以下も参照してください。: -
「基本認証スキーム」方式は、
RFC 2617 (基本認証スキーム)で説明されているように、base64 エンコードの HTTP ヘッダー承認に基づいています。
ユーザーエージェントがユーザーID「Alibaba」とパスワード「opensesame」を送信したい場合は、
次のヘッダーフィールドを使用します。
> Authorization: Basic QWxpYmFiYTpvcGVuIHNlc2FtZQ==注意:WWW-Authenticateヘッダーは、このメソッドで評価できます。以下も参照してください。: -
「標準認証スキーム」は、HTTP
リクエストに基づいています。ユーザーとパスワードはリクエストパラメーターから抽出されます。リクエストパラメーターの詳細については、パラメーターセクションを参照してください。この認証スキームの詳細については、Directory.authenticateUserFromLoginPasswordを参照してください。 -
「RESTフォワード認証スキーム」は、現在の認証済みセッションを再利用するユーザーサービスから REST サービスを呼び出す場合にのみ使用されます。詳細については、ユーザーサービスの実装を参照してください。REST データサービスを呼び出します。
-
「特定の認証スキーム」は、HTTP
リクエストに基づいています。たとえば、実装では、HTTPリクエストからパスワードダイジェストまたはチケットを抽出できます。詳細については、Directory.authenticateUserFromHttpRequestを参照してください。 -
「匿名認証スキーム」は、認証操作を処理する REST サービスにアクセスするためにのみ使用されます。認証情報の取得、パスワードの変更などは、ユーザーをまだ知ることができないことを意味します。
グローバル許可
グローバルアクセス権限は、REST ビルトインサービスと REST OpenAPI サービスに対して個別に定義できます。詳細については、グローバル許可を参照してください。
ルックアップメカニズム
EBX® はいくつかの認証方法を提供するため、条件に基づくルックアップメカニズムが設定され、特定の要求にどの方法を適用する必要があるかが分かります。メソッドの適用条件は、認証方式の優先度に従って評価されます。条件が満たされない場合、サーバーは次のメソッドを評価します。次の表に、サポートされている各プロトコルで使用可能な認証方法とその適用条件を示します。それらは、優先度の高いものから低いものの順に並べられます。
|
操作/プロトコル
|
認証方法と適用条件
|
|---|---|
|
REST / HTTP
|
|
同じリクエストに複数の認証方法が存在する場合、EBX® は HTTP コード
401 Unauthorized を返します。
監視
データサービスイベントは、EBX® メイン構成ファイルで宣言されているログカテゴリ
ebx.dataServices を介して監視できます。たとえば、 ebx.log4j.category.log.dataServices= INFO、ebxFile:dataservicesです。
以下も参照してください。:
SOAP と REST の比較
| 操作 | SOAP | REST |
|---|---|---|
| データ | ||
| メタモデルを選択 | X | |
| レコードを選択またはカウント (フィルターおよび/またはパブリケーションの表示を使用) | X | X |
| 関連値を持つレコードを選択 (第 1 レベル) | X | |
| レコードを更新または削除 (フィルターおよび/またはビューのパブリケーションを使用) | X | |
| 可能な列挙値のセレクター (フィルター付き) | X | |
| 作成または複製の準備 | X | |
| レコードの挿入、更新、または削除 | X | X |
| 履歴レコードを選択またはカウント (フィルターおよび/またはパブリケーションの表示を使用) | X | |
| データセットからノード値を選択 | X | X |
| データセットからノード値を更新 | X | |
| データスペースまたはスナップショット間のテーブルまたはデータセットの変更を取得 | X | |
| レプリケーションユニットを更新 | X | |
| レコードの認証情報を取得 | X | |
| サービス契約を生成 | WSDL | OpenAPI |
| ビュー | ||
| 公開されたテーブルビューを検索 | X | |
| データスペース | ||
| データスペースまたはスナップショット情報を選択 | X | |
| ルートまたは子のデータスペースを選択、またはスナップショットを選択 | X | |
| データスペースを作成、閉じる、マージ | X | X |
| スナップショットを作成、閉じる | X | X |
| データスペースまたはスナップショットを検証 | X | |
| データセットの検証 | X | |
| データスペースのロック、ロック解除 | X | X |
| ワークフロー | ||
| ワークフローの開始、再開、または終了 | X | |
| 管理 | ||
| デフォルトのディレクトリコンテンツ「ユーザー」、「ロール」... テーブルの管理 | X | X |
| ユーザーインターフェイスを開いて閉じる | X | X |
| 管理データセットを選択、挿入、更新、削除操作 | X | |
| システム情報を選択 | X | X |
| ステージング API | X (*) | |
| その他 | ||
| Java API から Web サービスを開発 | X (*) |
(*) 詳細については、REST Toolkit を参照してください。
制限事項
日付、時刻、日時の形式
データサービスは、次の日付と時刻の形式のみをサポートします。
| タイプ | 形式 | 例 |
|---|---|---|
| xs:date | yyyy-MM-dd | 2007-12-31 |
| xs:time | HH:mm:ss または HH:mm:ss.SSS | 11:55:00 |
| xs:dateTime | yyyy-MM-ddTHH:mm:ss または yyyy-MM-ddTHH:mm:ss.SSS | 2007-12-31T11:55:00 |
JMS
-
JMS プロトコルはサポートされていません。