Hitachi

uCosminexus Service Coordinator Interactive Workflow BPMN連携機能　使用の手引

11.1　REST APIの概要

HTTPリクエスト

REST APIのリクエストURLは，次に示すように，ドメイン名，コンテキストルート，APIバージョンおよびリソースアクセスパスから構成されます。

http(s)://<ドメイン>/<コンテキストルート>/<APIバージョン>/<リソースアクセスパス>

ドメインはWebサーバで設定します。RESTサービスのコンテキストルートはcsciwwsです。APIバージョンは，v1，v2などREST APIのバージョンがAPIごとに固定値として設定されます。残りの部分がリソースにアクセスするためのパスです。

HTTPメソッド

CSCIWのREST APIで使用するHTTPメソッドを次の表で示します。

表11‒1　HTTPメソッド

HTTPメソッド

内容

GET

リソースを取得します。

POST

リソースを新しく追加します。

PUT

指定されたリソースを修正します。

DELETE

指定されたリソースを削除します。

リクエストパラメタ

業務アプリケーションがRESTサービスにパラメタを渡す場合，クエリパラメタかリクエストボディを使用します。HTTPメソッドと，使用できるリクエストパラメタの関係を次の表で示します。

表11‒2　リクエストパラメタの送信方法

項番

リクエストパラメタ

GET

POST

PUT

DELETE

1

クエリパラメタ

○

×

×

○

2

リクエストボディ

△

○

○

×
（凡例）

○：利用できる

×：エラーが発生する

△：無視される

リクエストボディにパラメタを指定する場合，XML形式またはJSON形式で記載します。その際，HTTPヘッダのコンテンツタイプ（Content-Type）にapplication/xmlかapplication/jsonを指定する必要があります。コンテンツタイプにapplication/xmlかapplication/json以外の値が指定された場合や，未指定の場合はエラーになります。

使用できないリクエストパラメタを送信した場合，ステータスコード400のエラーが返されます。

リクエストボディに指定するパラメタをすべて省略する場合は，「リクエストパラメタ省略時のリクエストボディとHTTPヘッダ」を参照してください。

HTTPレスポンス

REST APIが正常終了した場合，HTTPレスポンスには，2xxのステータスコードが返されます。また，レスポンスボディにはリソースなどの情報が，XMLまたはJSON形式で返されます。コンテンツタイプはapplication/xmlまたはapplication/jsonです。レスポンスで返されるリソースの情報（プロセスデータは除く）については，マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「付録B.1 指定できる属性一覧」を参照してください。

レスポンスの形式は，HTTPヘッダの"Accept"にapplication/xmlまたはapplication/jsonを指定すると切り替わります。application/xmlまたはapplication/json以外の値が指定された場合はエラーになります。"Accept"が未指定の場合はXML形式で返されます。

REST APIがエラーになった場合，HTTPレスポンスには，3xx，4xxまたは5xxのステータスコードが返されます。また，レスポンスボディには次に示すようなエラードキュメントが返されます。エラーを受け取ったクライアントは，返却されたHTTPレスポンスと，ステータスコードに従ってエラーに対処できます。HTTPレスポンスのボディに設定しているメッセージにはエラーの詳細情報は付与されません。発生したエラーの詳細情報については，REST APIのログファイルを確認してください。

エラー時のレスポンスボディ（XMLの場合）

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <code>KDIWnnnnn-E</code>
  <message>メッセージ本文</message>
</error>

エラー時のレスポンスボディ（JSONの場合）

{
  "code" : "KDIWnnnnn-E",
  "message" : "メッセージ本文"
}

ユーザ記述子

REST APIが内部でJava APIを呼び出すとき，REST APIからJava APIにユーザ記述子を渡します。REST APIから渡すユーザ記述子のデフォルト値はcsciwwsです。デフォルト値とは異なるユーザ記述子を指定する場合は，共通設定ファイルのRestServiceUserDescriptionパラメタを変更するか，各REST APIのユーザ記述子のパラメタ（userdescription）を指定します。ユーザ記述子の長さは32バイト以下で指定してください。

ユーザ記述子については，マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「createCIWServer」を参照してください。

データ型と文字コード

業務アプリケーションとRESTサービスのリクエストとレスポンスでやり取りされるデータ型は，数値，文字列，配列，日付です。日付は，yyyy-MM-dd'T'HH:mm:ssZの形式（ISO 8601の拡張形式）で表します（例：2016-06-09T10:32:41+09:00）。レスポンスの文字コードはUTF-8です。

また，無限遠の日付の場合は日付の形式ではなく定数で表します。無限遠の未来の場合はBEYONDとなり，無限遠の過去の場合はORIGINとなります。

オブジェクトの状態および種類

CSCIWのオブジェクトの状態および種類と，それに対応する定数名とコード値の対応を次の表に示します。レスポンスでは，コード値を文字列型で返します。状態の定数名とコード値については，マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「付録B.2 指定できる属性値」の「(1)State属性で指定できる値」，および「付録C 状態遷移モデル」を参照してください。フローノードとフローノード定義の種類に関しては，定数名を返します。定数名の詳細については，次の記述を参照してください。

表11‒3　オブジェクトの状態および種類

状態および種類

定数名（コード値）

業務ステップの状態

INITIAL(i), READY(j), RUNNING(d), DISABLED(l), INTERMITTED(m), READY_FOR_TRANSITION(s), TRANSITION_COMPLETED(t), NOT_EXECUTED(p), TERMINATED(u), UNDEFINED(z)

業務ステップの種類

NORMAL(0), UNDEFINED(z)

ビジネスプロセス定義の状態

ACTIVE(b), INACTIVE(a), UNDEFINED(z)

作業定義の種類

BUILTIN_CONCURRENT_WORK(b), NORMAL(0), UNDEFINED(z)

案件の状態

NOT_STARTED(h), RUNNING(d), INTERMITTED(m), COMPLETED(o), TERMINATED(u), UNDEFINED(z)

作業の状態

INITIAL(i), READY(j), EXECUTING(e), PERFORMING(f), NOT_EXECUTED(p), CANCELED(q), EXECUTED(r), DISABLED(l), INTERMITTED(m), TERMINATED(u), UNDEFINED(z)

作業の種類

BUILTIN_CONCURRENT_WORK(b), NORMAL(0), UNDEFINED(z)

XMLとJSONの相違点

XMLの場合

  • リクエストボディとレスポンスにルート要素（<Parameter>や<ProcessInstances>など）を含みます。

  • タグを省略した場合にnullとして扱われます。

JSONの場合

  • リクエストボディとレスポンスにルート要素を含みません。このため，各REST APIのリクエストボディとレスポンスの構造に記載されているルート要素は無視されます。

  • 要素を省略した場合にnullとして扱われます。

  • Cosminexusアプリケーションサーバでは，値にnullが指定された場合は空文字として扱われます。

  • レスポンスの型が数値，またはboolean型の場合に，レスポンスはダブルクォーテーション「"」で囲われて返されます。

レスポンスの最大取得数

リソースの一覧を取得するREST APIの場合，レスポンスで取得できる最大データ件数を指定できます（デフォルト値は100件）。最大データ取得件数は，RestServiceResponseMaxCountパラメタにデフォルト値を設定するか，各REST APIの，リクエストパラメタに指定できます。

一覧取得のフィルター条件

リソースの一覧を取得するREST APIの場合，情報を絞り込むためのフィルター条件を設定できます。

日付型のデータを条件に指定する場合，1970/01/01 00:00:00 GMTを起点とした通算秒を指定する必要があります。日付が無限遠の過去の場合の通算秒は0となり，無限遠の未来の場合は9223372036854775となります。

Javaでの日付型データの変換例を次に示します。

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssXXX");
Date date = format.parse("2016-01-01T00:00:00+09:00");
// 1970/01/01 00:00:00 GMT を起点とした通算ミリ秒を取得し，通算秒に変換
long second = date.getTime() / 1000L;

String filterCondition = "StartDate<" + second;

REST APIでのプロセスデータの扱い

単一型プロセスデータを扱う場合

REST APIで単一型プロセスデータを扱う場合，次に示すようにProcessDataタグにプロセスデータキー名とプロセスデータ値を指定します。

XMLの場合

<ProcessDataList>
  <ProcessData>
    <Key>$SProduct</Key>
    <Value>cake</Value>
  </ProcessData>
  <ProcessData>
    <Key>$NStock</Key>
    <Value>30</Value>
  </ProcessData>
</ProcessDataList>

JSONの場合

"ProcessDataList" : {
  "ProcessData" : [
    {
      "Key" : "$SProduct",
      "Value" : "cake"
    },
    {
      "Key" : "$NStock",
      "Value" : "30"
    }
  ]
}
リスト型プロセスデータを扱う場合

REST APIでリスト型プロセスデータを扱う場合，次に示すように，key名の最後に{}を指定します。各データは定義されている順番にリスト化されます。また，リスト型プロセスデータの1要素を扱う場合は，key名の最後に{<リスト内識別子>}を指定します。

XMLの場合

<ProcessDataList>
  <ProcessData>
    <Key>$SProduct{}</Key>
    <Value>Bread</Value>
  </ProcessData>
  <ProcessData>
    <Key>$SProduct{}</Key>
    <Value>Butter</Value>
  </ProcessData>
  <ProcessData>
    <Key>$SProduct{}</Key>
    <Value>Strawberry</Value>
  </ProcessData>
  <ProcessData>
    <Key>$SProductCode{1}</Key>
    <Value>01234567895</Value>
  </ProcessData>
</ProcessDataList>

JSONの場合

"ProcessDataList" : {
  "ProcessData" : [
    {
      "Key" : "$SProduct{}",
      "Value" : "Bread"
    },
    {
      "Key" : "$SProduct{}",
      "Value" : "Butter"
    },
    {
      "Key" : "$SProduct{}",
      "Value" : "Strawberry"
    },
    {
      "Key" : "$SProductCode{1}",
      "Value" : "01234567895"
    }
  ]
}

リクエストパラメタ省略時のリクエストボディとHTTPヘッダ

一部のREST APIでは，リクエストボディに指定するパラメタをすべて省略できます。パラメタをすべて省略する場合は，リクエストボディを省略できます。リクエストボディを省略するときは，HTTPヘッダのContent-Typeを指定しないでください。リクエストボディを省略してContent-Typeを指定した場合の動作はサポートしません。

リクエストボディに指定するパラメタをすべて省略する場合のContent-Typeとリクエストボディの指定値を，次の表に示します。

表11‒4　Content-Typeとリクエストボディの指定値

項番

Content-Type

リクエストボディ

リクエストボディの例

1

指定しない

指定しない

−

2

application-xml

ルート要素だけ指定する

<Parameter/>

3

application-json

{}だけ指定する

{}
（凡例）

−：該当しない

ページの先頭へ