データサービスを使用すると、外部システムは、SOAP/Web サービス記述言語 (WSDL) 標準を使用して、TIBCO EBX® リポジトリで管理されているデータと対話できます。
SOAP 操作を呼び出すには、統合のユースケースで、データモデルから WSDL を生成する必要があります。次のような操作を実行できます。
レコードの選択、挿入、更新、削除、またはカウント
データセット値の選択
データスペースまたはスナップショット間、または同じデータモデルに基づく 2 つのデータセット間のテーブルの違いの取得
レコードの認証情報の取得
他の汎用 WSDL を生成して、次のような操作を実行できます。
データスペースの作成、マージ、またはクローズ
スナップショットの作成または終了
データセット、データスペース、またはスナップショットの検証
データワークフローの開始、再開、または終了
UI またはシステム情報へのアクセスを管理するための管理操作
SOAP と REST の比較を参照してください。
データサービスは、ebx-dataservices Web アプリケーションを他の EBX® モジュールとともに展開することで有効になります。詳細については、Java EE 展開の概要を参照してください。
リバースプロキシモードを使用するなど、特定の展開の場合、詳細については、URL コンピューティングを参照してください。
データサービスにアクセスするためのデフォルトの方法は HTTP 経由ですが、SOAP 操作に JMS を使用することもできます。詳細については、JMS 構成および JMS の使用を参照してください。
UTF-8 では、すべての入力メッセージが排他的である必要があります。すべての出力メッセージは UTF-8 です。
呼び出されるデータサービス操作によっては、セッション追跡情報を指定できる場合があります。
SOAP 操作の例では、リクエストヘッダーには次のものが含まれます。
<SOAP-ENV:Header> <!-- optional security header here --> <m:session xmlns:m="urn:ebx-schemas:dataservices_1.0"> <trackingInformation>String</trackingInformation> </m:session> </SOAP-ENV:Header>
詳細については、Java API の Session.getTrackingInfo を参照してください。
呼び出されるデータサービス操作に応じて、セッション入力パラメーターを指定できます。それらはリクエスト本文で定義されます。
入力パラメーターは、トリガー、アクセスルール、カスタム Web サービスなどのセッションオブジェクトを使用するカスタム Java コンポーネントで使用できます。これらは、データワークフロー操作でも使用できます。
SOAP 操作の例では、オプションのリクエストヘッダーには次のものが含まれます。
<SOAP-ENV:Header> <!-- optional security header here --> <m:session xmlns:m="urn:ebx-schemas:dataservices_1.0"> <!-- optional trackingInformation header here --> <inputParameters> <parameter> <name>String</name> <value>String</value> </parameter> <!-- for some other parameters, copy complex element 'parameter' --> </inputParameters> </m:session> </SOAP-ENV:Header>
詳細については、Java API の Session.getInputParameterValue を参照してください。
以下の実行時に予期しないサーバーエラーが発生した場合
SOAP 操作である SOAP 例外応答は、soap:Fault エレメントを介して呼び出し元に返されます。例を次に示します。
<soapenv:Fault> <faultcode>soapenv:java.lang.IllegalArgumentException</faultcode> <faultstring /> <faultactor>admin</faultactor> <detail> <m:StandardException xmlns:m="urn:ebx-schemas:dataservices_1.0"> <code>java.lang.IllegalArgumentException</code> <label/> <description>java.lang.IllegalArgumentException: Parent home not found at com.orchestranetworks.XX.YY.ZZ.AA.BB(AA.java:44) at com.orchestranetworks.XX.YY.ZZ.CC.DD(CC.java:40) ... </description> </m:StandardException> </detail> </soapenv:Fault>
HTTP の代わりに JMS を使用して SOAP 操作にアクセスすることが可能です。JMS アーキテクチャは、1 つの JMS リクエストキュー (必須)、1 つの JMS 障害キュー (オプション)、および JMS 応答キューに依存しています。JMS 構成を参照してください。必須のキューは入力キューです。リクエストメッセージは入力キューに配置する必要があり、応答メッセージは EBX® によって JMS リクエストの replyTo キューに配置されます。オプションのキューは、必要に応じて入力メッセージを再生できる障害キューです。構成ファイルでキューが設定およびアクティブ化され、リクエストメッセージの処理中に例外が発生した場合、この入力メッセージは障害キューにコピーされます。
リクエストと応答の関係は、JMS リクエストの messageId メッセージ識別子フィールドを応答の correlId 相関識別子フィールドにコピーすることによって作成されます。
生成された WSDL を特殊化するには、リネージ管理で JMS ロケーションポイントを定義する必要があります。特定のロケーションポイントが指定されていない場合、デフォルト値は jms:queue:jms/EBX_QueueIn になります。
コンテンツへのアクセスには認証が必須です。いくつかの認証方法が利用可能で、以下で説明されています。説明は優先度順に並べられています (EBX® は最も優先度の高い認証方式を最初に適用します)。
「基本認証スキーム」方式は、RFC 2617 (基本認証スキーム) で説明されているように、base64 エンコードの HTTP ヘッダー Authorization に基づいています。
ユーザーエージェントがユーザー ID「Alibaba」とパスワード「opensesame」を送信したい場合は、 次のヘッダーフィールドを使用します。 > Authorization: Basic QWxpYmFiYTpvcGVuIHNlc2FtZQ==
「標準認証スキーム」は、HTTP リクエストに基づいています。ユーザーとパスワードはリクエストパラメーターから抽出されます。リクエストパラメーターの詳細については、パラメーターセクションを参照してください。
この認証スキームの詳細については、Directory.authenticateUserFromLoginPassword を参照してください。
「SOAP セキュリティヘッダー認証スキーム」メソッドは、Web サービスセキュリティ UsernameToken プロファイル 1.0 仕様に基づいています。
デフォルトでは、タイプ PasswordText がサポートされています。これは、WSDL で定義されている次の SOAP ヘッダーを使用して実行されます。
<SOAP-ENV:Header> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext"> <wsse:UsernameToken> <wsse:Username>String</wsse:Username> <wsse:Password Type="wsse:PasswordText">String</wsse:Password> </wsse:UsernameToken> </wsse:Security> </SOAP-ENV:Header>
SOAP 操作でのみ使用できます。
「特定の認証スキーム」は、HTTP リクエストに基づいています。このメソッドの実装は、たとえば、HTTP リクエストからパスワードダイジェストまたはチケットを抽出できます。詳細については、Directory.authenticateUserFromHttpRequest を参照してください。
「SOAP 固有のヘッダー認証スキーム」。
詳細については、SOAP セキュリティヘッダーのオーバーライドを参照してください。
グローバルアクセス許可は、SOAP および WSDL コネクタアクセスに対して個別に定義できます。
別のセキュリティ認証メカニズムを定義するために、デフォルトの WSS ヘッダーをオーバーライドすることができます。このようなオーバーライドは、HTTP と JMS の両方で考慮されます。定義およびオーバーライドするには、[管理] > [リネージ] の下の [SOAP ヘッダーセキュリティ宣言] 構成設定を使用します。これには、次のフィールドが含まれます。
スキーマの場所 | WSDL にインポートするセキュリティ XML スキーマの URI |
ターゲット名前空間 | スキーマ内のエレメントのターゲット名前空間 |
名前空間のプレフィックス | ターゲット名前空間のプレフィックス |
メッセージ名 | WSDL で使用するメッセージ名 |
ルートエレメント名 | セキュリティヘッダーのルートエレメント名。名前は、スキーマで宣言されている名前と同じである必要があります。 |
wsdl:part エレメント名 | メッセージの |
デフォルトのセキュリティヘッダーをオーバーライドする目的は、セキュリティヘッダーに一致する WSDL メッセージの宣言を変更して、次の内容が含まれるようにすることです。
<wsdl:definitions ... xmlns:MyPrefix="MyTargetNameSpace" ...
...
<xs:schema ...>
<xs:import namespace="MyTargetNameSpace" schemaLocation="MySchemaURI"/>
...
</xs:schema>
...
<wsdl:message name="MySecurityMessage">
<wsdl:part name="MyPartElementName" element="MyPrefix:MySecurityRootElement"/>
</wsdl:message>
...
<wsdl:operation name="...">
<soap:operation soapAction="..." style="document"/>
<wsdl:input>
<soap:body use="literal"/>
<soap:header message="impl:MySecurityMessage" part="MyPartElementName" use="literal"/>
...
</wsdl:operation>
</wsdl:definitions>
対応する XML スキーマヘッダー宣言は次のようになります。
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="MyNameSpace"
xmlns:MyPrefix="MyNameSpace">
<element name="MySecurityRootElement" type="MyPrefix:SpecificSecurity"/>
<complexType name="SpecificSecurity">
<sequence>
<element name="AuthToken" type="string"/>
</sequence>
</complexType>
</schema>
上記の XML スキーマと構成を使用する SOAP メッセージには、次のヘッダーがあります。
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:MySecurityRootElement xmlns:m="MyNameSpace">
<AuthToken>String</AuthToken>
</m:MySecurityRootElement>
...
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
このデフォルト以外のヘッダーを処理するには、メソッド Directory.authenticateUserFromSOAPHeader を実装する必要があります。
SOAP 操作でのみ使用できます。
EBX® はいくつかの認証方法を提供するため、条件に基づくルックアップメカニズムが設定され、特定のリクエストにどの方法を適用する必要があるかが分かります。メソッドの適用条件は、認証方式の優先度に従って評価されます。条件が満たされない場合、サーバーは次のメソッドを評価します。次の表に、サポートされている各プロトコルで使用可能な認証方法とその適用条件を示します。それらは、優先度の高いものから低いものの順に並べられます。
操作/プロトコル | 認証方法と適用条件 |
|---|---|
SOAP / JMS |
|
SOAP / HTTP |
|
WSDL / HTTP |
|
同じリクエストに複数の認証方法が存在する場合、EBX® は HTTP コード 401 Unauthorized を返します。
データサービスイベントは、EBX® メイン構成ファイルで宣言されているログカテゴリ ebx.dataServices を介して監視できます。たとえば、ebx.log4j.category.log.dataServices= INFO、ebxFile:dataservices です。
操作 | 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 | |
システム情報を選択 | 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 |
データサービス操作の命名規則により、データモデル内で定義された各テーブルには、WSDL 生成の一意の名前が必要です。