付録H.10 RESTアプリケーションの開発
- 〈この項の構成〉
(1) リクエストデータ
RESTアプリケーションの開発時に従うリクエストデータの規定について説明します。
(a) リクエストライン
リクエストラインには,次に示す内容を指定できます。
Method:”GET” | “POST” | “PUT” | “DELETE”
Request-URI:任意のURI
リクエストラインの指定の詳細については,次の項目を参照してください。
-
Method:「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(b) rest.request.method」
-
Request-URI:「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(c) rest.request.url」
(b) リクエストヘッダ
リクエストヘッダには,任意の内容を指定できます。
リクエストヘッダの指定の詳細については,「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(d) rest.request.header.filepath」を参照してください。
(c) リクエストボディ
リクエストボディは,「付録H.10(3) ボディデータスキーマ(XML)」または「付録H.10(4) ボディデータスキーマ(JSON)」に示す,XMLまたはJSONのデータスキーマの内容に従って,作成してください。
(2) レスポンスデータ
RESTアプリケーションから返却されるレスポンスデータの規定について説明します。
(a) ステータスライン
RESTアプリケーションから返却されるステータスコードの判定結果を,次の表に示します。
項番 |
ステータスコード |
判定結果 |
---|---|---|
1 |
Informational 1xx |
成功 |
2 |
Successful 2xx |
成功 |
3 |
Redirection 3xx |
失敗 |
4 |
Client Error 4xx |
失敗 |
5 |
Server Error 5xx |
失敗 |
ステータスコードの判定結果が失敗の場合のアプリケーション呼び出しサービスの動作については,「付録H.4 障害時の動作」を参照してください。
(b) レスポンスヘッダ
レスポンスヘッダには,任意の内容を指定できます。
なお,セッションは継続されないため,Set-CookieヘッダのCookie情報は保持されません。
(c) レスポンスボディ
アプリケーション呼び出しサービスは,レスポンスボディを受け取らないため,レスポンスボディを指定する必要はありません。
レスポンスボディを省略した場合,ステータスコードは204(No Content)を返却してください。
(3) ボディデータスキーマ(XML)
- HTTPボディ部分のボディデータスキーマの内容
-
アプリケーション呼び出しサービスの送受信で使用されるHTTPボディ部分のボディデータスキーマの内容を,次に示します。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema elementFormDefault="qualified" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="csciwRestBody" type="csciwRestBodyType"/> <xs:complexType name="csciwRestBodyType"> <xs:sequence> <xs:element name="data" type="dataType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="dataType"> <xs:sequence> <xs:element name="key" type="xs:string"/> <xs:element name="value" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:complexType> </xs:schema>
- ボディデータスキーマ定義の要素の階層構造
-
項番
要素名および属性名※
型
型種別
数
1
csciwRestBody
csciwRestBodyType
混合型
1
2
data
dataType
混合型
0以上
3
key
xs:string
−
1
4
value
xs:string
−
0〜1
- ボディデータスキーマ宣言
-
項番
宣言
属性
値
説明
1
XML宣言
version
1.0
XMLのバージョンを指定します。
1.0が固定値です。
2
encoding
UTF-8
エンコードを指定します。
3
standalone
yes
外部のmarkup宣言の有無について指定します。
スタンドアロン文書のため,yesを指定してください。
4
schema宣言
elementFormDefault
qualified
ローカル要素にも名前空間接頭辞を付与するために,指定します。
5
version
1.0
XMLスキーマのバージョンを指定します。
1.0が固定値です。
6
xmlns:xs
http://www.w3.org/2001/XMLSchema
名前空間"xs"を宣言するために,指定します。
- ボディデータの出力例
-
上記のスキーマが適用されたボディデータの出力例を次に示します。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <csciwRestBody> <data> <key>key1</key> <value>value1</value> </data> <data> <key>key2</key> <value>2</value> </data> <data> <key>ListData</key> <value>AAA</value> </data> <data> <key>ListData</key> <value>BBB</value> </data> </csciwRestBody>
(4) ボディデータスキーマ(JSON)
- HTTPボディ部分のボディデータスキーマの内容
-
アプリケーション呼び出しサービスの送受信で使用されるHTTPボディ部分のボディデータスキーマの内容を,次に示します。
{ "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "key": { "type": "string", "required": true }, "value": { "type": ["string", "null"] } } } } } }
- ボディデータスキーマ定義の要素の階層構造
-
項番
要素名および属性名※
型
型種別
数
制約
1
data
array
配列
0以上
−
2
key
string
文字列
1
null不可
3
value
string
文字列
0〜1
null不可
- ボディデータの出力例
-
上記のスキーマが適用されたボディデータの出力例を次に示します。
{ "data":[ { "key":"K1", "value":"V1"}, { "key":"K2", "value":"V2"} ] }
(5) XML形式のボディデータのスキーマ変換
アプリケーション呼び出しサービスのボディデータスキーマと異なるデータスキーマを持つRESTアプリケーションを呼び出したい場合は,各データスキーマにデータ構造変換のためのスタイルシートを指定する必要があります。
ボディデータのスキーマ変換の手順を次の図に示します。
- <説明>
-
- 開発時
-
-
リクエストボディのデータのマッピング
XSLTスタイルシートを作成するツールを使用して,入力スキーマおよび出力スキーマに次に示すボディデータスキーマを指定して,リクエストボディデータをマッピングします。
・入力スキーマ:CSCIWのリクエストのボディデータスキーマ
・出力スキーマ:RESTアプリケーションのリクエストのボディデータスキーマ
-
マッピング内容のスタイルシートの作成
XSLTスタイルシートを作成するツールを使用して,マッピングした内容のスタイルシートを作成します。
-
アプリケーション呼び出しサービスへのスタイルシートの指定
指定方法の詳細については,「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(e) rest.request.stylesheet.filepath」を参照してください。
-
- 実行時
-
-
指定されたスタイルシートに従ったボディデータの変換
アプリケーション呼び出しサービスがRESTアプリケーションにリクエストを送信する際,指定されたスタイルシートの内容に従って,CSCIWのリクエストボディのデータがRESTアプリケーションのリクエストボディのスキーマに変換されます。
-
(6) RESTアプリケーションの開発時の注意事項
アプリケーション呼び出しサービスは,RESTアプリケーションの呼び出しに失敗した場合,リトライによってRESTアプリケーションを複数回呼び出します。また,アプリケーション呼び出しサービスを強制停止するなどして直後の作業が完了しなかった場合,RESTアプリケーションの呼び出しに成功しても,再度RESTアプリケーションを呼び出します。この場合は,リトライ回数の設定に関係なく再度呼び出します。そのため,RESTアプリケーションが複数回呼び出されても正常に動作するように,べき等性を保証した実装をしてください。
(7) RESTアプリケーションの実装例
RESTアプリケーションの実装例を示します。
(a) PartsInfoService.java
PartsInfoService.javaは,RESTアプリケーションのルートリソースクラスのソースファイルです。「<コンテキストルート> + "/parts/order"」のURLに対するPOSTリクエストを受信するリソースメソッドorderを持っています。
- PartsInfoService.javaの実装例
package xxx.usrapp; import java.util.List; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.core.Response; import javax.ws.rs.core.Response.Status; /** * RESTアプリケーションを実装したクラスです。 */ @Path("/parts") public class PartsInfoService { /** * 呼び出されるメソッドです。 * * @param reqData リクエストデータ * @return レスポンス(204応答) */ @POST @Path("order") public Response order(CSCIWRestBody reqData) { // リクエストデータの取得 if(reqData != null) { List<CSCIWData> list = reqData.getDataList(); if(list != null) { for(CSCIWData d : list) { System.out.println(String.format( "AppInfo: key=%1$s, value=%2$s", d.getKey(), d.getValue())); } } } // 204応答を返す return Response.status( Status.NO_CONTENT).build(); } }
(b) CSCIWRestBody.java
CSCIWRestBody.javaは,RESTアプリケーションが送受信するエンティティのcsciwRestBody要素のソースファイルです。CSCIWRestBody.javaは,data要素を子要素として持っています。data要素は,任意の数を指定できます。
- CSCIWRestBody.javaの実装例
package xxx.usrapp; import java.util.ArrayList; import java.util.List; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; /** * RESTアプリケーション送受信データのクラスです。 */ @XmlRootElement(name="csciwRestBody") public class CSCIWRestBody { private List<CSCIWData> list = new ArrayList<CSCIWData>(); @XmlElement(name="data") public List<CSCIWData> getDataList() { return list; } public void setDataList(List<CSCIWData> l) { list = l; } /** * 指定されたデータをリストに追加します。 * @param data 追加するデータ */ public void add(CSCIWData data) { list.add(data); } }
(c) CSCIWData.java
CSCIWData.javaは,RESTアプリケーションが送受信するエンティティのcsciwRestBody要素の子要素である,data要素のソースファイルです。data要素は,子要素としてkey要素およびvalue要素を1つずつ持っています。key要素およびvalue要素のデータ型は,string型です。
- CSCIWData.javaの実装例
package xxx.usrapp; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; /** * RESTアプリケーション送受信データのクラスです。 */ @XmlRootElement(name="data") public class CSCIWData { private String key = ""; //キー private String value = ""; //値 /** コンストラクタ */ public CSCIWData(){} public CSCIWData(String k, String v){ key = k; value = v; } @XmlElement(name="key") public String getKey() { return key; } public void setKey(String k) { key = k; } @XmlElement(name="value") public String getValue() { return value; } public void setValue(String v) { value = v; } }
(d) アプリケーション呼び出し情報ファイルの記述例
アプリケーション呼び出し情報ファイルの記述例を示します。この例でのref識別子の値は,「ope1」とします。
type=REST rest.request.url=http://localhost/CSPWCOMockApp/parts/order rest.request.method=POST rest.request.header.filepath=/home/csciw/ope1header.properties rest.request.body.key.offset=0
アプリケーション呼び出し情報ファイルのファイルパスは,「<BpmnCallInformationFileDirプロパティの指定値>/ope/ope1.properties」です。
なお,アプリケーション呼び出し情報ファイルのrest.request.header.filepathプロパティで設定しているHTTPヘッダファイルの記述例は,次のとおりです。
Content-type: application/xml;charset=UTF-8
(e) アプリケーション呼び出し制御情報の設定例
この例では,ref識別子の値が「ope1」の作業に対して,アプリケーション呼び出し制御情報を設定します。
- ヒント
-
アプリケーション呼び出し制御情報は,環境構築時のデフォルトの動作でも問題ない場合,設定は不要です。環境構築時のデフォルトの動作とは,ref識別子共通設定のデフォルト値での動作のことです。
アプリケーション呼び出し制御情報およびref識別子共通設定については,マニュアル「uCosminexus Service Coordinator Interactive Workflow コマンド」の「ciwmngap(アプリケーション呼び出し制御情報の管理)」を参照してください。
この例でのアプリケーション呼び出し制御情報に設定する値,およびciwmngapコマンドを使用したアプリケーション呼び出し制御情報の設定例を次に示します。
アプリケーション呼び出し制御情報に設定する値
-
ref識別子:ope1
-
実行間隔:180(単位:秒)
-
リトライ間隔:900(単位:秒)
-
リトライ回数:0(単位:回)
-
最大作業件数:10000(単位:件)
-
障害復旧間隔:1500(単位:秒)
アプリケーション呼び出し制御情報の設定例
-
アプリケーション呼び出し制御情報ファイルの作成
アプリケーション呼び出し制御情報を更新するための入力用ファイルである,アプリケーション呼び出し制御情報ファイルを作成します。
次に示すアプリケーション呼び出し制御情報ファイルの記入例では,「アプリケーション呼び出し制御情報に設定する値」で示した各値を記入しています。
アプリケーション呼び出し制御情報ファイルの記入例
#UPDATEOPTION,REFTYPE,REF,EXECUTEINTERVAL,RETRYINTERVAL,RETRYCOUNT,WORKITEMMAX,RECOVERYTIME U,ope,ope1,180,900,0,10000,1500
-
ciwmngapコマンドの実行
作成したアプリケーション呼び出し制御情報ファイルの内容を適用するために,アプリケーション呼び出し制御情報ファイルのファイルパスを指定したciwmngapコマンドを実行します。
ciwmngapコマンドの指定形式
ciwmngap -sid <システムID> -chg -apdf <アプリケーション呼び出し制御情報ファイルのファイルパス>
- ヒント
-
アプリケーション呼び出し制御情報ファイルおよびciwmngapコマンドについては,マニュアル「uCosminexus Service Coordinator Interactive Workflow コマンド」の「ciwmngap(アプリケーション呼び出し制御情報の管理)」を参照してください。