付録H.9　RESTアプリケーションの開発

〈この項の構成〉

(1)　リクエストデータ
(2)　レスポンスデータ
(3)　ボディデータスキーマ（XML）
(4)　ボディデータスキーマ（JSON）
(5)　XML形式のボディデータのスキーマ変換
(6)　RESTアプリケーションの開発時の注意事項
(7)　RESTアプリケーションの実装例

(1)　リクエストデータ

RESTアプリケーションの開発時に従うリクエストデータの規定について説明します。

(a)　リクエストライン

リクエストラインには，次に示す内容を指定できます。

Method：”GET” | “POST” | “PUT” | “DELETE”

Request-URI：任意のURI

リクエストラインの指定の詳細については，次の項目を参照してください。

Method：「付録H.12(9)　アプリケーション呼び出し情報ファイルに指定する内容」の「(b)　rest.request.method」
Request-URI：「付録H.12(9)　アプリケーション呼び出し情報ファイルに指定する内容」の「(c)　rest.request.url」

(b)　リクエストヘッダ

リクエストヘッダには，任意の内容を指定できます。

リクエストヘッダの指定の詳細については，「付録H.12(9)　アプリケーション呼び出し情報ファイルに指定する内容」の「(d)　rest.request.header.filepath」を参照してください。

(c)　リクエストボディ

リクエストボディは，「付録H.9(3)　ボディデータスキーマ（XML）」または「付録H.9(4)　ボディデータスキーマ（JSON）」に示す，XMLまたはJSONのデータスキーマの内容に従って，作成してください。

ページの先頭へ

(2)　レスポンスデータ

RESTアプリケーションから返却されるレスポンスデータの規定について説明します。

(a)　ステータスライン

RESTアプリケーションから返却されるステータスコードの判定結果を，次の表に示します。

表H‒3　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アプリケーションを呼び出したい場合は，各データスキーマにデータ構造変換のためのスタイルシートを指定する必要があります。

ボディデータのスキーマ変換の手順を次の図に示します。

図H‒10　ボディデータのスキーマ変換

＜説明＞

開発時

リクエストボディのデータのマッピング

XSLTスタイルシートを作成するツールを使用して，入力スキーマおよび出力スキーマに次に示すボディデータスキーマを指定して，リクエストボディデータをマッピングします。

・入力スキーマ：CSCIWのリクエストのボディデータスキーマ

・出力スキーマ：RESTアプリケーションのリクエストのボディデータスキーマ
マッピング内容のスタイルシートの作成

XSLTスタイルシートを作成するツールを使用して，マッピングした内容のスタイルシートを作成します。
アプリケーション呼び出しサービスへのスタイルシートの指定

指定方法の詳細については，「付録H.12(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（アプリケーション呼び出し制御情報の管理）」を参照してください。

ページの先頭へ

付録H.9 RESTアプリケーションの開発

(1) リクエストデータ

(a) リクエストライン

(b) リクエストヘッダ

(c) リクエストボディ

(2) レスポンスデータ

(a) ステータスライン

(b) レスポンスヘッダ

(c) レスポンスボディ

(3) ボディデータスキーマ（XML）

(4) ボディデータスキーマ（JSON）

(5) XML形式のボディデータのスキーマ変換

(6) RESTアプリケーションの開発時の注意事項

(7) RESTアプリケーションの実装例

(a) PartsInfoService.java

(b) CSCIWRestBody.java

(c) CSCIWData.java

(d) アプリケーション呼び出し情報ファイルの記述例

(e) アプリケーション呼び出し制御情報の設定例

付録H.9　RESTアプリケーションの開発

(1)　リクエストデータ

(a)　リクエストライン

(b)　リクエストヘッダ

(c)　リクエストボディ

(2)　レスポンスデータ

(a)　ステータスライン

(b)　レスポンスヘッダ

(c)　レスポンスボディ

(3)　ボディデータスキーマ（XML）

(4)　ボディデータスキーマ（JSON）

(5)　XML形式のボディデータのスキーマ変換

(6)　RESTアプリケーションの開発時の注意事項

(7)　RESTアプリケーションの実装例

(a)　PartsInfoService.java

(b)　CSCIWRestBody.java

(c)　CSCIWData.java

(d)　アプリケーション呼び出し情報ファイルの記述例

(e)　アプリケーション呼び出し制御情報の設定例