21.1 運用設定
ここでは、Web APIクライアント機能を設定し、運用するための手順について解説します。
21.1.1 Web APIクライアント用マスター情報の作成
Web APIクライアント機能による処理を行うためには以下の設定が必要です。
- PKI系マスター情報の作成（任意）
HTTP認証サーバー（OAuth 2.0使用時）およびHTTP認証情報（任意）、Web APIリクエストアプリケーション、フローの作成については別途後述します。
21.1.2 PKI系マスター情報の作成（任意）
接続先のWeb APIサービスがHTTPSで提供されている場合は、PKI系マスター情報（キーペアや認証局の証明書など）の作成が必要です。HTTPで提供されている場合には登録する必要はありません。
HTTP認証サーバーに指定された認証先がHTTPSで提供されている場合も、同様にPKI系マスター情報の作成が必要です。
| マスター情報 | 説明 |
|---|---|
| 認証局の証明書 | HTTPSで提供されているWeb APIサービスに接続する場合は必須です。接続先Web APIサービスが提供する認証局の証明書を登録する必要があります。詳細については『4 通信機能の概要』の「4.4.3 認証局の証明書」を参照してください。 |
| キーペア | 接続先Web APIサービスに接続する際の認証方式に、クライアント証明書による認証を用いる場合は必須です。 詳細については『4 通信機能の概要』の「4.4.1 キーペア」を参照してください。 |
- サーバー証明書の詳細検証
接続先のWeb APIサービスが提示するサーバー証明書を信頼できるか検証を実施します。
検証のために、認証局の証明書に登録されている証明書を用います。JDKに付属するルート認証局の証明書は使用しません。
検証時には、サーバー証明書のCommon Nameが接続先ホスト名と一致するかどうかの確認も行います。両者が一致しない場合は、接続先が正しくないと判断し、リクエストは失敗したものとみなしてタスクを障害にします。
セキュリティレベルは下がりますが、Common Nameの検証を省略することができます。指定方法については「Aプロパティ」の「apl.http.client.server.verification」と「http.auth.server.server.verification」を参照してください。
21.1.3 HTTP認証サーバーの作成（任意）
HTTP認証で認証方式「OAuth 2.0」を利用する場合には、本マスター情報の作成が必要です。本マスター情報には接続方式に関する内容を登録し、HTTP認証情報側に接続に利用するアカウント情報を登録します。本マスター情報に対して、複数のHTTP認証情報を登録できます。
HTTP認証サーバーを作成するには、メニューの「HTTP認証サーバー」を選択し、一覧画面右上の「新規作成」を押下します。
21.1.3.1 基本情報
項目名 | 説明 |
|---|---|
業務グループ | HTTP認証サーバーが所属する業務グループを指定します。 ●EDI（対外接続） WG-ED ●基幹システムとの接続 WG-ES |
HTTP認証サーバー名 | HTTP認証サーバーを一意に特定するための名前を指定します。 |
認可フロー | 認可サーバーに接続する際に使用する認可フローを指定します。
|
貸出 | 指定された業務グループ専用とするか、他の業務グループでも利用可能とするかを選択します。 |
注釈 | HTTP認証サーバーに関する注釈を指定します。 |
21.1.3.2 OAuth 2.0情報
項目名 | 説明 |
|---|---|
トークンエンドポイント | 認可サーバーが提供するトークンエンドポイントのURLを指定します。 httpかhttpsから始まるURLを指定します。 |
失効エンドポイント | 認可サーバーが提供する失効エンドポイントのURLを指定します。 httpかhttpsから始まるURLを指定します。 |
有効にするセキュアプロトコル | 認可サーバー接続時に、TLSで有効とするプロトコル（TLSv1.2など）を指定します。SSLは指定できません。 未指定の場合には使用するJDKの実装に依存します。 |
SSL/TLSサーバー認証で使用する認証局グループ | 認可サーバー接続時に、TLSサーバー認証で「限定的な用途で信頼する」認証局グループを使用する場合に指定します。 未指定の場合には「システム全体で信頼する」認証局グループを使用します。 |
クライアント認証タイプ | 認可サーバー接続時に行う、クライアント認証のタイプを指定します。
|
アクセストークン有効期間(秒) | アクセストークン取得時に認可サーバーから有効期間が返却されない場合に使用する、アクセストークンの有効期間(秒)を指定します。 認可サーバー側のドキュメント等で指定される値を指定します。 |
追加するリクエストヘッダー | トークンエンドポイントへのリクエストに任意のヘッダーを追加する場合に指定します。認可サーバーが独自のヘッダーを必要とする場合に指定してください。 |
追加するPOSTパラメーター | トークンエンドポイントへのリクエストのPOSTパラメーターに任意のパラメーターを追加する場合に指定します。認可サーバーが独自のパラメーターを必要とする場合に指定してください。 別の設定項目により決定する以下のパラメーターは指定できません。
|
リフレッシュトークン有効期間(秒) | リフレッシュトークンの有効期間(秒)を指定します。 認可サーバー側のドキュメント等で指定される値を指定します。 |
21.1.3.3 プロパティ
HTTP認証サーバーのプロパティを用いることで、次の指定を行うことができます。
- TLS接続時のサーバー証明書の詳細検証の有無
- 回線トレースの出力方法およびマスク処理の有無
これらはHTTP認証側にも指定できます。どちらにも指定した場合はHTTP認証側の値が採用されます。
■TLS接続時のサーバー証明書の詳細検証
認証サーバーに対してTLSを用いて接続する際に、接続先のサーバー証明書の検証を行うかどうかを制御できます。詳細については「21.1.2 PKI系マスター情報の作成（任意）」を、指定内容については「21.1.4 HTTP認証情報の作成（任意）」を参照してください。
■回線トレースの出力方法およびマスク処理
認証サーバーに対して接続する際に、そのリクエストとレスポンスの内容を記録するかどうかを制御できます。詳細については「21.1.6 Web APIリクエストアプリケーションの作成」の「21.1.6.5 Web APIリクエスト詳細情報」を、指定内容については「21.1.4 HTTP認証情報の作成（任意）」を参照してください。
回線トレースは障害時の調査に用いることが多いため、デフォルトではアプリケーション側の指定に従います。認証サーバーへ接続する際の回線トレースの出し方を明示的に制御する必要があるときに指定します。たとえば、「回線トレースを出すかどうかはアプリケーション側の指定に従うが、マスク処理は常に行う」といったことを実現できます。
21.1.4 HTTP認証情報の作成（任意）
接続先のWeb APIサービスが何らかの認証を要求する場合には、本マスター情報の作成が必要です。
HTTP認証情報を作成するには、メニューの「HTTP認証情報」を選択し、一覧画面右上の「新規作成」を押下します。その後に表示されるダイアログで、作成する認証方式を選びます。
21.1.4.1 基本情報
項目名 | 説明 |
|---|---|
業務グループ | HTTP認証情報が所属する業務グループを指定します。 ●EDI（対外接続） WG-ED ●基幹システムとの接続 WG-ES |
認証ID | HTTP認証情報を一意に特定するための名前を指定します。 |
認証方式 | 新規作成時に選択した認証方式が表示されます。
|
認証内容設定タイプ | 認証に関する情報をリクエストのどの場所に設定するか選択します。
|
貸出 | 指定された業務グループ専用とするか、他の業務グループでも利用可能とするかを選択します。 |
注釈 | HTTP認証情報に関する注釈を指定します。 |
21.1.4.2 認証情報
認証方式によって表示される内容が異なるため、以降は個別に説明します。
■Basic認証
項目名 | 説明 |
|---|---|
ユーザー | Basic認証に用いるユーザーを指定します。 |
パスワード | Basic認証に用いるパスワードを指定します。 |
■APIキー認証
項目名 | 説明 |
|---|---|
キー名 | APIキー認証をする際のキー名を指定します。 認証内容設定タイプが「リクエストヘッダー」の場合は、リクエストヘッダー名を指定し、「URLパラメーター」の場合は、URLパラメーター名を指定します。 |
APIキー値 | APIキー認証に用いるAPIキーの値を指定します。 |
■クライアント証明書による認証
項目名 | 説明 |
|---|---|
キーペア名 | クライアント証明書による認証に用いるキーペアを指定します。 少なくとも1つのキーペアを指定する必要があります。 |
利用期間 | キーペアの有効期間に従うかどうかを指定します。キーペアの有効期限に従わない場合、利用開始日時、利用終了日時を設定する必要があります。 |
利用開始日時 | キーペアの有効期限に従わない場合の利用開始日時を指定します。キーペアの有効期間内の任意の日時を指定してください。 |
利用終了日時 | キーペアの有効期限に従わない場合の利用終了日時を指定します。キーペアの有効期間内の任意の日時を指定してください。 |
■OAuth 2.0
項目名 | 説明 |
|---|---|
認可フロー | 認可サーバーに接続する際に使用する認可フローを指定します。
|
HTTP認証サーバー名 | HTTP認証サーバーを指定します。 |
有効なリフレッシュトークン | リフレッシュトークンフローで使用する、有効なリフレッシュトークンの有無を表示します。 |
有効期限 | リフレッシュトークンフローで使用する、有効なリフレッシュトークンの有効期限を表示します。 |
クライアントID | 認可サーバーから発行されたクライアントIDを指定します。 |
クライアントシークレット | 認可サーバーから発行されたクライアントシークレットを指定します。 |
ユーザー名 | パスワードフローで使用する、認可サーバーに登録済みのユーザー名を指定します。 |
パスワード | パスワードフローで使用する、認可サーバーに登録済みのパスワードを指定します。 |
JWT情報名 | JWTアサーションフローで使用するJWT情報を指定します。 |
スコープ | 未指定の場合は認可サーバーに設定されたスコープに従います。それよりも限られた範囲のスコープでリソースサーバーにアクセスする場合に指定します。 |
追加するリクエストヘッダー | トークンエンドポイントへのリクエストに任意のヘッダーを追加する場合に指定します。認可サーバーが独自のヘッダーを必要とする場合に指定してください。 この項目はHTTP認証サーバーの設定を引き継ぎます。詳細は本章で後述します。 |
追加するPOSTパラメーター | トークンエンドポイントへのリクエストのPOSTパラメーターに任意のパラメーターを追加する場合に指定します。認可サーバーが独自のパラメーターを必要とする場合に指定してください。 別の設定項目により決定するパラメーターは指定できません。対象のパラメーターは「21.1.3 HTTP認証サーバーの作成（任意）」の「21.1.3.2 OAuth 2.0情報」の「追加するPOSTパラメーター」を参照してください。この項目はHTTP認証サーバーの設定を引き継ぎます。詳細は本章で後述します。 |
「追加するリクエストヘッダー」と「追加するPOSTパラメーター」は、「HTTP認証サーバー名」で指定されたHTTP認証サーバーの設定を引き継ぎます。
例えば、認可サーバーで固定のパラメーターが必要な場合はHTTP認証サーバーで共通的に指定し、クライアント毎に異なるパラメーターが必要な場合はHTTP認証情報に指定するといった運用を想定しています。
21.1.4.3 リフレッシュトークンの登録
OAuth 2.0タイプのHTTP認証情報を作成し、リフレッシュトークンフローを用いてOAuth 2.0のアクセストークンを取得する場合には、リフレッシュトークンを登録する必要があります。
認可フローにリフレッシュトークンフローを選択したHTTP認証情報を保存した後に、アクションの「リフレッシュトークン登録」を選択することでリフレッシュトークンを登録できます。
項目名 | 説明 |
|---|---|
リフレッシュトークン | 認可サーバーから発行されたリフレッシュトークンを指定します。 |
正常に登録ができると「有効なリフレッシュトークン」に「あり」と表示されます。また「有効期限」には、アクションを実施した日時に対してHTTP認証サーバーの「リフレッシュトークンの有効期間」の値を加算したものが表示されます。
21.1.5 JWT情報の作成（任意）
HTTP認証で認証方式「OAuth 2.0」を利用し、認可フローを「JWTアサーションフロー」にする場合は、本マスター情報の作成が必要です。
JWT情報を作成するには、メニューの「JWT情報」を選択し、一覧画面右上の「新規作成」を押下します。
21.1.5.1 基本情報
項目名 | 説明 |
|---|---|
業務グループ | JWT情報が所属する業務グループを指定します。 EDI、基幹システム連携での利用で指定する名称が異なります。 ●EDI（対外接続） WG-ED ●基幹システムとの接続 WG-ES |
JWT情報名 | JWT情報を一意に特定するための名前を指定します。 |
貸出 | 指定された業務グループ専用とするか、他の業務グループでも利用可能とするかを選択します。 |
注釈 | JWT情報に関する注釈を指定します。 |
21.1.5.2 署名に関する情報
項目名 | 説明 |
|---|---|
アルゴリズム(alg) | 署名のアルゴリズムを指定します。algヘッダーの値に設定されます。 下記が指定可能です。
|
署名で利用する共通鍵 | 署名で利用する共通鍵を指定します。 下記のアルゴリズムの場合に指定する必要があります。
|
署名で利用するキーペア | 署名で利用する秘密鍵を格納したキーペアを指定します。 下記のアルゴリズムの場合に指定する必要があります。
キーペア情報の項目は後述の「署名で利用するキーペア」を参照してください。 |
■署名で利用するキーペア
キーペアは2つ設定できます。JWTアサーション生成時の署名には、利用開始日時が早いキーペアを利用します。JWTアサーション生成時に利用期間内のキーペアが存在しない場合は、JWTアサーションの生成が失敗します。
項目名 | 説明 |
|---|---|
キーペア名 | 署名で利用するキーペアを指定します。 |
利用期間 | キーペアの有効期間に従うかどうかを指定します。キーペアの有効期限に従わない場合、利用開始日時、利用終了日時を設定する必要があります。 |
利用開始日時 | キーペアの利用開始日時を指定します。キーペアの有効期間内の任意の日時を指定してください。 未指定の場合はキーペアの有効開始日が自動設定されます。 |
利用終了日時 | キーペアの利用終了日時を指定します。キーペアの有効期間内の任意の日時を指定してください。 未指定の場合はキーペアの有効終了日が自動設定されます。 |
21.1.5.3 ヘッダーとペイロード
項目名 | 説明 |
|---|---|
JWSヘッダー情報 | JWSのヘッダーを追加します。 algヘッダーは「アルゴリズム(alg)」の指定値を使うため、この項目での設定はできません。 |
発行後の有効期間(秒) (exp) | JWTアサーションの有効期間を秒で指定します。JWTアサーションの生成日時から指定された秒数経過後の日時をUNIXエポック秒で数値化してexpクレームの値に設定します。 指定しない場合はexpクレームを含めません。 |
有効開始日時 (nbf) | JWTアサーションの有効開始日時であるnbfクレームの設定方法を指定します。
[発行日時を指定する]を選択した場合は、JWTアサーションの生成日時をUNIXエポック秒で数値化してnbfクレームの値に設定します。 |
発行日時 (iat) | JWTアサーションの発行日時であるiatクレームの有無を指定します。 指定する場合は、JWTアサーションの生成日時をUNIXエポック秒で数値化してiatクレームの値に設定します。 |
JWT識別値 (jti) | JWTアサーションの識別値であるjtiクレームの有無を指定します。 指定する場合は、ACMS Cloud内で一意な文字列（16文字）をjtiクレームの値に設定します。 |
JWTクレーム情報 | JWSにおけるペイロードのクレーム情報を追加します。 この項目で下記クレームを設定した場合は、その値が優先されます。
|
■JWSヘッダー情報
項目名 | 説明 |
|---|---|
ヘッダー名 | JWSのヘッダー名を指定します。 |
タイプ | 値のタイプを指定します。詳細は後述の「値のタイプ」を参照してください。 |
値 | JWSヘッダーの値を指定します。 |
■JWTクレーム情報
項目名 | 説明 |
|---|---|
クレーム名 | クレーム名を指定します。 |
タイプ | 値のタイプを指定します。詳細は後述の「値のタイプ」を参照してください。 |
値 | クレームの値を指定します。 |
■値のタイプ
JSONにおける値のタイプを指定します。
- 文字列
値を文字列として扱う場合に指定します。
指定する値をエスケープする必要はありません。JWTアサーション生成時にエスケープ処理されます。
- 数値
値を数値として扱う場合に指定します。
- JSON文法
JSON文法における値部分に埋め込まれる文法を直接指定します。
「true」、「false」、「null」といったリテラルや、「 [“key1” : “value”, “key2” : 1000] 」といった配列を指定できます。
下記にJWTクレーム情報の設定値と形成されるペイロード部のJSONの例を示します。
JWTクレーム情報
クレーム名 | タイプ | 値 |
|---|---|---|
iss | 文字列 | acms-cloud-jwt@jwt-test-example.dal.com |
aud | JSON文法 | “example01.dal.co.jp”,”example02.dal.co.jp”] |
org-exp | 数値 | 1643863909 |
org-bln | JSON文法 | true |
形成されるペイロード部のJSON
{
“iss”: “acms-cloud-jwt@jwt-test-example.dal.com”,
“aud”: [
“example01.dal.co.jp”,
“example02.dal.co.jp”
],
“org-exp”: 1643863909,
“org-bln”: true
}
21.1.6 Web APIリクエストアプリケーションの作成
Web APIのリクエストを実施するためのアプリケーションを作成します。
アプリケーションを作成するには、メニューの「アプリケーション」を選択し、アプリケーションタイプが「Web APIリクエスト」のアプリケーションのアクションから「ラップアプリを作成する」を押下します。
ラップアプリの詳細については、『20 フローを設定する』の「20.3.1 ベースアプリケーションとラップアプリケーション」を参照してください。
21.1.6.1 基本情報（アプリケーション共通部）
項目名 | 説明 |
|---|---|
業務グループ | アプリケーションが所属する業務グループを指定します。 EDI、基幹システム連携での利用で指定する名称が異なります。 ●EDI（対外接続） WG-ED ●基幹システムとの接続 WG-ES |
アプリケーション名 | アプリケーションを一意に特定するための名前を指定します。 |
アプリケーションタイプ | アプリケーションの種類が表示されます。 |
ラップ元アプリ名 | アプリケーションのベースとなるアプリケーション名が表示されます。 |
貸出 | 指定された業務グループ専用とするか、他の業務グループでも利用可能とするかを選択します。 |
注釈 | アプリケーションに関する注釈を指定します。 |
21.1.6.2 基本情報（Web APIリクエスト固有部）
項目名 | 説明 |
|---|---|
接続先ベースURL | Web APIのリクエストを行う先のURLを指定します。httpかhttpsから始まるURLを指定します。スキームとホスト部だけではなく、パスを含めることもできます。 例）https://example.com:8080/api/v2 |
リソースパス | 接続先ベースURLに続くパスを指定します。リソースパスにはマクロを使用できます。 例）/orders |
リクエストメソッド | Web APIのリクエストを行う際のメソッドを指定します。GETやPOSTなどRFCで明示されたもの以外も指定できます。 |
タスクへの出力を制限 | リクエストヘッダーに含まれるCookieとSet-Cookie、X-CSRF-Tokenの値をタスクの出力パラメーターに記録するか選択します。 複数回のWeb APIリクエストを行う際に、Set-Cookieの値やX-CSRF-Tokenの値を引き継ぐ必要がある場合には、「しない」を選択する必要があります。 |
■接続先ベースURLとリソースパス
リクエストを実施する際には、接続先ベースURLとリソースパスを結合した値をリクエストラインに指定します。たとえば、接続先ベースURLに「http://example.com/api/v2」と指定され、リソースパスに「/orders/2020-01-01」と指定されていた場合は、「http://example.com/api/v2/orders/2020-01-01」となります。接続先ベースURLとリソースパスの間に「/」が存在しない場合は「/」が補完されます。
なお、ドメイン部はPunycode化し、その他はパーセントエンコードします。そのため空白などが含まれる場合でもそのまま入力できます。
21.1.6.3 Web APIリクエスト情報
項目名 | 説明 |
|---|---|
有効にするセキュアプロトコル | TLSで有効とするプロトコル（TLSv1.2など）を指定します。SSLは指定できません。 未指定の場合には使用するJDKの実装に依存します。 接続先ベースURLを指定したとき、かつhttpsの場合のみ指定できます。 |
SSL/TLSサーバー認証で使用する認証局グループ | TLSサーバー認証で「限定的な用途で信頼する」認証局グループを使用する場合に指定します。 未指定の場合には「システム全体で信頼する」認証局グループを使用します。 接続先ベースURLを指定したとき、かつhttpsの場合のみ指定できます。 |
追加するURLパラメーター | 任意のURLパラメーターを追加する場合に指定します。 |
追加するリクエストヘッダー | 任意のリクエストヘッダーを追加する場合に指定します。 |
追加するリクエストボディ | リクエストにボディを含める場合に指定します。 |
■追加するURLパラメーター
リクエストするURL（接続先ベースURLとリソースパスを結合したもの）に対して、URLパラメーターを追加する場合に用います。
追加するURLパラメーターの新規作成ボタンを押下することで、次図ダイアログから登録できます。
項目名 | 説明 |
|---|---|
パラメーター名 | URLパラメーターの名称を指定します。 |
パラメーター値 | URLパラメーターの値を指定します。値にはマクロを使用できます。 |
必須区分 | マクロを展開した結果のパラメーター値が存在する必要があるのか、存在しなくてもよいのかを選択します。 パラメーター値が指定されなかった（省略された）場合は、次のようになります。
|
未指定時の出力方法 | 必須区分がオプションで、パラメーター値が指定されなかった（省略された）場合にパラメーターをどのように出力するかを選択します。
|
デフォルト値 | 未指定時の出力方法が「デフォルト値を出力する」の場合に出力する値を指定します。 |
■追加するリクエストヘッダー
リクエストする際に、任意のリクエストヘッダーを追加する場合に用います。
追加するリクエストヘッダーの新規作成ボタンを押下することで、次図ダイアログから登録できます。
項目名 | 説明 |
|---|---|
ヘッダー名 | リクエストヘッダーの名称を指定します。 |
ヘッダー値 | リクエストヘッダーの値を指定します。値にはマクロを使用できます。 |
必須区分 | マクロを展開した結果のヘッダー値が存在する必要があるのか、存在しなくてもよいのかを選択します。 ヘッダー値が指定されなかった（省略された）場合は、次のようになります。
|
未指定時の出力方法 | 必須区分がオプションで、ヘッダー値が指定されなかった（省略された）場合にヘッダーをどのように出力するかを選択します。
|
デフォルト値 | 未指定時の出力方法が「デフォルト値を出力する」の場合に出力する値を指定します。 |
■追加するリクエストボディ
リクエストボディを追加してリクエストする場合に用います。元となるデータを次の3つから選択します。
- 入力データ：前段ジョブタスクの出力ファイル
- テンプレート：「テンプレート」に指定した値
- マルチパート： 「マルチパート情報」の定義
入力データかテンプレートを選択した場合と、マルチパートを選択した場合とで表示される項目が異なります。以降ではそれぞれの項目について説明をします。
■入力データ/テンプレート
項目名 | 説明 |
|---|---|
リクエストボディのContent-Type | 入力データを表すContent-Typeを指定します。マクロを使用できます。 未指定の場合は「application/octet-stream」として扱います。 |
テンプレート | リクエストボディのテンプレートを指定します。 追加するリクエストボディに「テンプレート」を選択した場合に指定します。 指定できる値は改行を含めて最大1,000文字です。比較的軽量なリクエストボディでの利用を想定しています。1,000文字を超える場合は「入力データ」を利用してください。 |
テンプレート用マッピング定義 | リクエストボディに対する置換処理を定義します。 詳細は「21.2.3 リクエストボディ置換処理の利用」を参照してください。 |
リクエストのチャンク転送 | リクエストボディをチャンク転送するか選択します。 |
■マルチパート
multipart/form-data形式のリクエストボディの情報を登録します。
項目名 | 説明 |
|---|---|
boundary | マルチパートフォームデータのバウンダリを指定します。 未指定の場合はシステムが自動生成したバウンダリが設定されます。特定のバウンダリ文字列を送信する必要がある場合のみ設定してください。 |
個々のパート情報は次図のダイアログで登録できます。
項目名 | 説明 |
|---|---|
パート名 | パートの識別名称です。 |
フィールド名 | Content-Dispositionヘッダーのnameパラメーターの値を指定します。 |
ファイル名 | Content-Dispositionヘッダーのfilenameパラメーターの値を指定します。 |
ファイル名Charset | ファイル名のキャラクターセットを指定します。未指定の場合はUTF-8です。 |
Content-Type | パート内のContent-Typeヘッダーを指定します。 |
追加するリクエストヘッダー | パート内に追加する任意のヘッダーを指定します。 詳細は前項の「追加するリクエストヘッダー」を参照してください。 |
ボディタイプ | パート内ボディのデータを選択します。
|
テンプレート | パート内ボディのテンプレートを指定します。 ボディタイプに「テンプレート」を選択した場合に指定します。 指定できる値は改行を含めて最大1,000文字です。比較的軽量なリクエストボディでの利用を想定しています。1,000文字を超える場合は「入力データ」を利用してください。 |
マッピング定義 | パート内ボディに対するマッピング定義を指定します。 詳細は「21.2.3 リクエストボディ置換処理の利用」を参照してください。この章では「追加するリクエストボディ」と「テンプレート用マッピング定義」における置換処理の利用について説明していますが、マルチパート情報の「パート内ボディ」と「マッピング定義」における置換処理と読み替えることができます。 |
21.1.6.4 Web APIレスポンス解析情報
項目名 | 説明 |
|---|---|
レスポンスコンテンツ形式 | レスポンスボディのフォーマットを指定します。 成否判定条件のボディ階層を指定した際は、ここで指定されたフォーマットに従って解析します。 |
成否判定条件 | レスポンスされた情報から、リクエストの成否を判定するための条件を指定します。 条件には以下の3つがあり、指定されたものすべてが合致する必要があります。 ステータスコード レスポンスヘッダー ボディ 上位に定義されたものから順に判定し、最初に合致した条件を採用します。 詳細については「21.2.1 レスポンスの成否判定と終了状態の結びつけ」を参照してください。 |
21.1.6.5 Web APIリクエスト詳細情報
項目名 | 説明 |
|---|---|
認証方式 | リクエストを実施する際の認証方式を選択します。
|
認証情報 | 認証方式が認証なし以外の場合に、HTTP認証情報の名称を指定します。 |
21.1.6.6 アプリ実行結果情報
Web APIクライアント機能として特別な扱いはありません。
詳細は『20 フローを設定する』の「20.3.2 アプリケーション共通の設定」を参照してください。
21.1.6.7 実行制御情報
Web APIクライアント機能として特別な扱いはありません。
詳細は『20 フローを設定する』の「20.3.2 アプリケーション共通の設定」を参照してください。
21.1.7 フローの作成
Web APIクライアント機能を組み込んだフローを作成します。
業務および接続先Web APIサービスの仕様に合わせて、必要な箇所にWeb APIリクエストジョブを配置します。
ここではサンプルとして、出荷業務実施後にWeb APIサービス側の出荷伝票を更新するシナリオのフローを作成します。
21.1.7.1 作成するフローの流れ
次のような流れでフローの処理を作成します。
最初にGET処理でWeb APIサービスから出荷に関する情報を取得（Get-OutboundDeliveryジョブ）し、その後にWebAPIリクエスト経由で社内システムの出荷業務に指示を出します。
その後はPATCH処理でWeb APIサービス側の出荷伝票を更新（Update-OutboundDeliveryジョブ）し、それと並行して取引先への出荷を案内します。
なお、フォーマット変換やエラー処理に関しては省略しています。
21.1.7.2 フロー入力パラメーター
出荷業務を実施するためには、少なくとも「何を対象に出荷するのか」を判断できなければ処理できません。そのため、フローにある「フロー入力パラメーター」で、「出荷伝票番号」を受け取る想定でフローを作成します。
ここでは「delivery_id」として受け取るようにします。
21.1.7.3 Get-OutboundDeliveryジョブ
このジョブでは、フロー入力パラメーターで受け取った出荷伝票番号を元に、Web APIサービスから出荷伝票の明細を取得します。
後続ジョブで更新を実施するため、「タスクへの出力を制限」を「しない」に設定し、Cookieの情報を引き継げるようにしています。
また次図のように、出荷伝票番号をURLパラメーターに指定します。ここではODataの$filterを使って指定しています。
21.1.7.4 Update-OutboundDeliveryジョブ
このジョブでは、出荷業務で更新された情報を元に、Web APIサービスの出荷伝票を更新します。GET時と同じセッションで更新を実施するため、GET時のタスクに出力しておいたSet-Cookieの値をリクエストヘッダーに含めます。
ここでは簡略化するためにCookieについてのみ言及しましたが、Web APIサービス側の仕様に合わせて、If-MatchやX-CSRF-Tokenなどのリクエストヘッダーを適切に指定する必要があります。
21.1.7.5 Logoutジョブ
Cookieを用いた一連の処理が終わった後に、不要となったセッションを破棄するためにログアウトします。
ログアウトの仕方はWeb APIサービス側の仕様に合わせて実施する必要があります。
21.1.8 リクエストの実行
「ロード（フロー）」を用いて、対象のフローを指定して実行します。ほかにも、通信の後に実行することや、フローの中からフローチェインで実行することができます。
ロードの詳細については『3 ACMS Cloudの概要と基本操作』の「3.4.2 ロード」を参照してください。
21.1.9 回線トレース情報をタスクの出力ファイルとして記録
Web APIリクエストアプリケーションが実施した一連のリクエスト・レスポンスの回線トレース情報を、アプリジョブタスクの出力ファイルとして記録することができます。OAuth 2.0におけるトークンリクエスト・レスポンスの回線トレース情報も一緒に記録できます。アプリジョブタスクの出力ファイルとして記録するので、タスク詳細画面を介してダウンロードすることができます。
記録する情報は後述します。
本機能は専用のプロパティを指定することで利用できます。詳細は後述します。
本機能は常時利用ではなく障害時の調査や導入時の検証に利用することを推奨します。以下のコストが発生するためです。
- Web APIリクエスト送受信処理に出力ファイル記録時間のオーバーヘッド発生
- データストアのディスク使用 （回線トレース情報記録分）
その他、後述する「21.1.9.3 仕様の詳細と注意事項」もご確認ください。
■回線トレース
回線トレースは、Web APIリクエストアプリケーションが実施した一連のリクエスト・レスポンスの内容を記録するための機能です。接続先Web APIサービスに意図したとおりにリクエストができなかった場合など、障害時の原因調査に有用です。
回線トレースにはリクエストヘッダーとレスポンスヘッダーの内容が記録されます。リダイレクトなどで複数回のリクエストが発生する際には、それらも回線トレースに残ります。
デフォルトではリクエストとレスポンスのボディ内容は出力されませんが、出力するかどうかをプロパティで制御できます。指定内容については「A プロパティ」を参照してください。但し、レスポンスのボディ内容の出力は1MBまでとなり、1MBを超えた場合は1MB分出力された後に[MORE]の文言が出力されます。
21.1.9.1 利用方法
回線トレース情報をタスクの出力ファイルとして記録する機能を利用するには、専用のプロパティを指定する必要があります。
■プロパティ
Web APIリクエストアプリケーションに次のプロパティを指定します。
キー名 | 説明 |
|---|---|
apl.http.client.output.verification |
※デフォルトは「false」です。 |
OAuth 2.0におけるトークンリクエストの出力要否も上記プロパティに従います。トークンリクエストの情報だけ記録したくないといった場合は「HTTP認証情報」もしくは「HTTP認証サーバー」に次のプロパティを指定して制御します。
キー名 | 説明 |
|---|---|
http.auth.server.output.verification |
※デフォルトはWeb APIリクエスト側の出力要否に従います。 |
ただし、トークンリクエストの情報だけを記録するといった使い方は出来ません。Web APIリクエスト側で「true（出力する）」を指定していない場合、トークンリクエスト側のプロパティを「true（出力する）」にしても回線トレース情報の記録は行いません。
21.1.9.2 照会方法
出力ファイルに記録した回線トレース情報は、Web APIリクエストのアプリジョブタスクの詳細画面からダウンロードできます。
通常はタスクの個別出力情報として記録します。下図のように出力パラメーターが「_task_output_contents=VERIFICATION」である出力情報からダウンロードできます。
なお、こちらは「タスク出力対象」の設定を「レスポンスボディ」にしていた場合の例です。他の出力情報については「21.2.4タスク出力対象の使い分け」を参照してください。
トークンリクエストで認証エラーなどの応答が返った場合は、下図のように「出力ファイル」のリンクからダウンロードします。トークンリクエストに失敗した場合はWeb APIリクエストの実行に至らないので、タスクの出力ファイルに記録する対象が「トークンリクエストで生じた回線トレース情報の記録」の1件のみとなるためです。
21.1.9.3 仕様の詳細と注意事項
本機能の仕様の詳細と注意事項を紹介します。
■一連のリクエスト・レスポンスの内容は1つの出力ファイルに記録
Web APIリクエストアプリケーションが実施した一連のリクエスト・レスポンスの内容は1つの出力ファイルに記録します。例えば認証方式にOAuth 2.0を利用した場合はトークンエンドポイントへのリクエストとWeb APIリクエストの2つのリクエストが発生しますが、それらを1つの出力ファイルに発生した順番に記録します。
■回線トレース情報を記録した出力ファイルは後続タスクに連携しない
回線トレース情報を記録した出力ファイルは後続タスクに連携しません。
例えば、Web APIリクエストアプリケーションの「タスク出力対象」を「両方」にしたうえで本機能を有効にした場合のタスクの個別出力情報は下表の通りとなります。これに後続ジョブを配置した場合、レスポンスボディを利用した後続ジョブタスクの実行と、入力ファイルを利用した後続ジョブタスクの実行の2つのみ発生します。
出力パラメータ | 出力ファイルの内容 | 後続タスクへの連携 |
|---|---|---|
_task_output_contents=RESPONSE_BODY | レスポンスボディ | 連携する |
_task_output_contents=INPUT_FILE | 入力ファイル | 連携する |
_task_output_contents=VERIFICATION | 回線トレース情報 | 連携しない |
■リクエストヘッダー・レスポンスヘッダーのマスク処理
Web APIリクエストにおける一連のリクエストヘッダー・レスポンスヘッダーに含まれるCookieや認証に関わる情報はマスク処理します。マスク処理しないようにする場合はWeb APIリクエストアプリケーションに次のプロパティを指定します。
キー名 | 説明 |
|---|---|
apl.http.client.output.verification.encrypt |
※デフォルトは「true」です。 |
トークンリクエストに対してのマスク要否も上記プロパティに従います。トークンリクエストに対してだけマスク処理の要否を制御したい場合は「HTTP認証情報」もしくは「HTTP認証サーバー」に次のプロパティを指定します。
キー名 | 説明 |
|---|---|
http.auth.server.output.verification.encrypt |
※デフォルトはWeb APIリクエスト側のマスク処理要否に従います。 |
リクエストやレスポンスには、認証に関わる情報やCookieなどが含まれます。回線トレースを出力する場合には、これらの情報も回線トレースに出力されます。
これらの値がそのまま出力されるとセキュリティ上のリスクにつながるため、次に挙げる項目を回線トレース上でマスクします。マスクされた内容を確認する必要がある場合は、「マスクしない」に変更します。
- HTTP認証情報に指定された値（Basic認証やAPIキー認証の内容）
- CookieとSet-Cookieの値
- X-CSRF-Tokenの値
■レスポンスボディの記録は1MBまで
レスポンスのボディ内容の出力は1MBまでとなり、1MBを超えた場合は1MB分出力した後に[MORE]の文言を出力します。
■クリーンアップにより削除される
当該のアプリジョブタスクがクリーンアップで削除されることで、回線トレースを記録した出力ファイルも一緒に削除されます。
21.1.10 フローエディター
前項のフロー基本設定が完了したら、次に業務処理の流れを定義します。
ACMS Cloudではフローエディターを使って、視覚的にわかりやすく業務処理の流れを定義することができます。
フローエディターでフローを定義する手順は以下の通りです。
- フローを新規登録するために、フロー一覧画面右上の「新規作成」ボタンを押下します。
- 「新規作成」ボタン押下後に表示されるフロー詳細画面で、前記のフローの基本設定項目を設定します。
- フローエディターを開くにはフロー定義画面上部のフローエディタータブを押下します。
初期のフローエディター画面には開始ジョブが自動で配置されます。
- 画面右側のパレットからフローに組み込みたいジョブをドラッグアンドドロップします。
- ドロップした直後のジョブはジョブ定義を行っていない状態のため、エラーの存在を示す赤いアイコン、ないしは警告の存在を示す黄色いアイコンで表示されます。
- アプリケーションジョブを配置する場合には、パレットの「コントロールジョブ」を「アプリケーションジョブ」に切り替えてください。
- ジョブ定義を行うにはジョブアイコンをクリックします。
- アプリケーションジョブの場合、まずは定義されているアプリケーションの中から該当ジョブで実行するアプリケーション名を選択します。
- 各ジョブ定義の設定項目の意味については、後述の「コントロールジョブの設定」、「アプリケーション設定」を参照してください。
- ジョブ定義内にエラーが存在する場合、エラーを解消するまでジョブ定義を保存することができません。
- ジョブアイコン右側の丸とジョブアイコン左側の丸とをドラッグアンドドロップし、処理したい順番にジョブを接続します。
- 誤って配置したジョブや、データフローは対象を選択した後に、画面上部の「削除」ボタンを押下することで削除することができます。また、削除ボタン左の矢印アイコンで「元に戻す」、「やり直し」を行うことができます。
- ジョブ定義、およびデータフローによるジョブの接続が完了したら、画面右上の「保存」ボタンを押下してフロー定義を保存します。
21.1.11 ジョブの入出力データフロー
ジョブ名称 | 入力データフロー | 出力データフロー | 後続実行 |
|---|---|---|---|
RACCOON | 1 | 1 | 1～N |
圧縮 | 1 | 1 | 1 |
解凍 | 1 | 1 | 1～N |
Web APIリクエスト | 1 | 1 | 1 |
開始 | × | 1 | 1 |
単独通信チェイン | 1 | × | × |
※出力データフローが”×”のジョブは、終端にのみ設置可能であることを意味します。
21.2 高度な利用方法
ここでは、Web APIクライアント機能の高度な使い方について解説します。
21.2.1 レスポンスの成否判定と終了状態の結びつけ
リクエストが成功したかどうかはレスポンスのステータスコードで判断できます。しかしWeb APIサービスの仕様によっては、ステータスコード以外の情報も判断した上で、リクエストを正常終了とするのか障害とするのかを決めるケースもあります。たとえば、ステータスコードとしては400が返ってきたが、レスポンスヘッダーに「X-Count: 0」があるときには正常終了として扱うといったケースです。
このようなときは成否判定条件を作成し、終了状態と結びつけることによって実現できます。
21.2.1.1 リクエストの成否判定の概要
リクエストの成否は、利用者が定義したリクエストの成否判定条件を元に決定します。成否判定条件は複数登録でき、定義されている上位のものから順番に比較し、マッチした成否判定条件を採用します。
次図はレスポンス内容が「400」の場合のイメージです。上から順番に判定し、2番目の成否判定条件を採用します。
成否判定の処理は、実行対象のアプリケーションに指定された成否判定条件を用いて判定し、それに合致しない場合はラップ元アプリケーションで定義したものを用いて判定します。
21.2.1.2 成否判定条件の指定方法
Web APIレスポンス解析情報にある「成否判定条件」を追加します。成否判定条件には次のものを使用できます。これらが同時に指定された場合は、AND条件で判定します。
- ステータスライン内のステータスコード（reason-phraseは対象外）
- 任意のレスポンスヘッダーの値
- レスポンスボディ内部の値
項目名 | 説明 |
|---|---|
exitコード | 条件に合致した際のexitコードを指定します。 このexitコードと「終了状態」にあるexitコードが一致したものをアプリケーションの実行結果として採用します。 |
ステータスコード | ステータスコードの値と比較するための値を指定します。正規表現を用いた指定ができます。 |
ヘッダー名 | 比較対象のレスポンスヘッダー名を指定します。 |
ヘッダー値 | レスポンスヘッダーの値と比較するための値を指定します。正規表現を用いた指定ができます。 |
ボディ階層 | 比較対象のレスポンスボディの階層を指定します。 詳細は「21.2.2 レスポンスボディによる成否判定」を参照してください。 |
ボディ値 | ボディの値と比較するための値を指定します。正規表現を用いた指定ができます。 |
21.2.1.3 終了状態との結びつけ
終了状態には、「正常終了」と「一時障害」、「即時障害」の登録がされています。これをそのまま使うことも、成否判定条件に合わせて追加することもできます。
次図のように、成否判定条件にあるexitコードと終了状態にあるexitコードを一致させることで、判定した結果を正常終了させることも、障害にすることもできます。
すべての成否判定条件に一致しなかった場合は、即時障害として扱います。
21.2.2 レスポンスボディによる成否判定
レスポンスのステータスコードで成否を判断できるが、レスポンスボディに詳細なエラーコードが含まれるWeb APIが提供されていることがあります。このエラーコードを元に成否判定をする必要がある場合は、「ボディ階層」と「ボディ値」を指定することで実現できます。
21.2.2.1 解析可能なコンテンツ形式
レスポンスボディの内容を元に成否判定をするため、ボディのファイル形式を適切に認識できる必要があります。「レスポンスコンテンツ形式」の項目でファイル形式を指定します。ここにはJSONとXML、テキスト、バイナリのいずれかを指定できますが、ボディの解析が可能なのはJSONとXMLのみです。
レスポンスボディの解析には、レスポンスヘッダーのContent-Typeに指定されたcharsetの値を用います。charsetの指定がない場合は、UTF-8として解析します。
21.2.2.2 ボディ階層の指定
「ボディ階層」には、ACMS Cloud独自の式を指定します。たとえば「reason」や「Status/ErrorCode」のように、レスポンスボディ上の階層構造を指定します。コンテンツ形式を問わず、階層構造が同じであれば同じ式を使えます。
ボディ階層を表す式は次のルールに従って記載します。
- 階層の名称は大文字と小文字を区別する
- 階層の区切りには”/”を用いる
- 階層の名称に”/”か”\”が含まれる場合は、”\”を用いてエスケープする
■JSONのボディ階層
JSONでは階層の名称部分にオブジェクトの名前を指定します。JSONの構造には配列が存在することもありますが、ボディ階層に配列を指定することはできません。
また、ボディ階層に指定したオブジェクトのバリュー部は、文字列か数字、true、false、nullのいずれかである必要があります。オブジェクトや配列がセットされているようなケースでは値を取得できません。
次に、サンプルのJSON構造を元にボディ階層の指定例を示します。
レスポンスボディ | ボディ階層の指定例 | 取得できる値 |
|---|---|---|
{ “data1” : “AAA”, “data2” : { “data.3” : 123, “data/4” : true } } | data1 | AAA |
data2 | オブジェクト構造そのものは取得できない | |
data.3 | 最上位の階層に存在しないので取得できない | |
data2/data.3 | 123 | |
data2/data/4 | “/”がエスケープされていないので取得できない | |
data2/data\/4 | true |
■XMLのボディ階層
XMLでは階層の名称部分に要素の名前を指定します。XMLの構造には属性やCDATAなどが存在することもありますが、ボディ階層にこれらを指定することはできません。
また、ボディ階層に指定した要素内に、文字データのみが含まれている必要があります。文字データと要素が混在するようなケースでは値を取得できません。
次に、サンプルのXML構造を元にボディ階層の指定例を示します。
レスポンスボディ | ボディ階層の指定例 | 取得できる値 |
|---|---|---|
<root> <data1>AAA</data1> <data2 attr=”XYZ”> <data3> 123<br/> </data3> <data4>true</data4> </data2> </root> | root/data1 | AAA |
root/data2 | 文字データのみではないため取得できない | |
root/data2/attr | 属性の値は取得できない | |
root/data2/data3 | 文字データのみではないため取得できない | |
root/data2/data4 | true |
21.2.2.3 XPathの指定
レスポンスコンテンツ形式が「XML」である場合、ボディ階層にXPathを指定できます。これにより、XML形式のレスポンスボディを使った成否判定をより柔軟に行うことができます。
シンプルな構成のXMLで且つ特定の要素の値を使った成否判定を行う場合は「21.2.2.2 ボディ階層の指定」の通り階層を表す式で実現できます。ただし、要素の有無や数、あるいは属性の値などを条件に判定を行いたい場合は、XPathを利用してください。
XPathを利用する場合は、ボディ階層に「XPath:{XPath言語}」と指定します。ボディ値にはその結果を指定します。
利用できるXPathのバージョンは1.0です。
例えば下記XMLなら、ボディ階層「XPath:/root/data[2]」、ボディ値「200」と指定することで一致判定となります。
<root><data>100</data><data>200</data></root>
21.2.3 リクエストボディ置換処理の利用
追加するリクエストボディに対して特定の文字列による置換処理が行えます。
Web APIリクエスト情報の「テンプレート用マッピング定義」により、置換対象となる文字列と置換後の値を定義できます。
SOAPメッセージのようにタグや属性などの構造がある程度定型化されており、特定の要素の値だけを切替えて（置換して）メッセージを形成するといった運用が想定されます。リクエストボディをテンプレート部とマッピング文字で構成することで、この運用をサポートします。
この章では、テンプレート用マッピング定義の運用設定の説明と設定例の解説をします。
21.2.3.1 テンプレート用マッピング定義の運用設定
テンプレート用マッピング定義は、追加するリクエストボディが「入力データ」と「テンプレート」、「マルチパート」のときに使用できます。「マルチパート」の場合は「マッピング定義」と称します。
置換後の値にはパラメーターマクロを利用できます。（パラメーターマクロについては「20.1.1.1 パラメーターマクロ」を参照してください。）また、置換後の値を前段ジョブタスクの出力ファイルの内容にすることもできます。
項目名 | 説明 |
|---|---|
必須区分 | マッピング値に該当するデータが前段ジョブタスクから連携されなかった場合の実行時の挙動を指定します。
なお、データが連携されないパターンは次の2つです。
|
マッピング名称 | 置換対象となる文字列を指定します。 |
マッピング値タイプ | 置換後の値のタイプを指定します。
追加するリクエストボディが「入力データ」の場合は、マッピング値タイプを「入力データ」にすることはできません。 |
マッピング値 | 置換後の値を指定します。 パラメーターマクロを指定できます。 |
デフォルト値タイプ | マッピング値に該当するデータが前段ジョブタスクから連携されなかった場合のデフォルト値のタイプを指定します。
|
デフォルト値 | マッピング値に該当するデータが前段ジョブタスクから連携されなかった場合のデフォルト値を指定します。 |
マッピング値に利用する出力パラメーターの値が空文字、あるいは出力ファイルが0byte であった場合でも、前段ジョブタスクからデータが連携されたものと判断します。したがって、デフォルト値の適用はされません。マッピング値の置換後の値は空文字となります。
21.2.3.2 テンプレート用マッピング定義の利用例
テンプレート用マッピング定義を利用してリクエストボディを動的に形成することができます。
本章では、SOAP通信におけるリクエストボディをテンプレート用マッピング定義で形成する場合の定義を解説します。
- 追加するリクエストボディは「テンプレート」項目の値を利用
- エンベロープの特定要素を前段タスクから連携された出力パラメーター、および出力ファイルを利用して置換
- SOAP1.1 とする
■Web APIリクエスト情報
項目 | 指定値 |
|---|---|
追加するリクエストヘッダー | SOAPAction を指定します。指定内容は後述します。 |
追加するリクエストボディ | テンプレート |
リクエストボディのContent-Type | text/xml |
テンプレート | SOAPメッセージを指定します。指定内容は後述します。 |
テンプレート用マッピング定義 | エンベロープの特定要素を前段タスクから連携された出力パラメーター、および出力ファイルを利用して置換させるための定義を指定します。指定内容は後述します。 |
■追加するリクエストヘッダー
リクエストヘッダーにSOAPAction情報をセットします。本章では直接指定します。
項目 | 指定値 |
|---|---|
ヘッダー名 | SOAPAction |
ヘッダー値 | http://example.com/sample/hoge/sample-client |
■テンプレート
リクエストボディとなるSOAPメッセージを指定します。
<?xml version=”1.0″ encoding=”utf-8″?>
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
<soap:Header>
<MessageHeader xmlns=”http://example.com/sample/hoge/sample-client”>
<MessageId>#message_id#</MessageId>
<Timestamp>#timestamp#</Timestamp>
</MessageHeader>
</soap:Header>
<soap:Body>
<MessageBody xmlns=”http://example.com/sample/hoge/sample-client”>
<MessageId>#message_id#</MessageId>
<data datatype=”#datatype#” >#data#</data>
</MessageBody>
</soap:Body>
</soap:Envelope>
■テンプレート用マッピング定義
# | 必須区分 | ﾏｯﾋﾟﾝｸﾞ名称 | ﾏｯﾋﾟﾝｸﾞ値ﾀｲﾌﾟ | ﾏｯﾋﾟﾝｸﾞ値 | ﾃﾞﾌｫﾙﾄ値ﾀｲﾌﾟ | ﾃﾞﾌｫﾙﾄ値 |
|---|---|---|---|---|---|---|
1 | 必須 | #message_id# | 任意の値 | $messageid$ | 任意の値 | <指定なし> |
2 | オプション | #data# | 入力データ | <指定なし> | 任意の値 | NoData |
3 | オプション | #datatype# | 任意の値 | $datatype$ | 任意の値 | string |
4 | 必須 | #timestamp# | 任意の値 | $datetime$ | 任意の値 | <指定なし> |
「#message_id#」と「#timestamp#」、「#datatype#」は前段ジョブタスクの出力パラメーターの値で置換します。それぞれのマッピング値にはパラメーターマクロを指定しています。
「#message_id#」と「#timestamp#」は必須ですので、前段ジョブタスクの出力パラメーターに「messageid」と「datetime」が登録されていない場合は実行時エラーとなります。
「#datatype#」はオプションですので、前段ジョブタスクの出力パラメーターに「datatype」が登録されていない場合はデフォルト値である「string」という文字列で置換されます。
「#data#」は前段ジョブタスクの出力ファイルの内容で置換します。出力ファイルが無い場合はデフォルト値である「NoData」という文字列で置換されます。
マッピング名称は、テンプレートとなるリクエストボディの内容（タグ名や要素名、その他名前空間など）と予期せず一致してしまうことを避けるため、任意の記号などで囲ってください。本章では「#」で囲っています。
21.2.4 タスク出力対象の使い分け
タスクの「出力ファイル」の対象を下記から選択できます。
- レスポンスボディを出力ファイルとする
- 入力ファイルをそのまま出力ファイルとする
- レスポンスボディと入力ファイルをそれぞれ個別の出力情報として扱う
それぞれWeb APIリクエストの目的に合わせて使い分けてください。
■入力データを使用する
セッションの維持やCSRF対策を目的に、トークン発行要求用のWeb APIリクエストを中継させてトークン情報を後続ジョブに引き継ぐといった運用も想定されます。このように、トークン情報を連携しつつフローで扱うデータファイルはそのまま後続のジョブに連携したい場合に、トークン発行要求用のWeb APIリクエストのタスク出力対象を「入力データ」にします。
A プロパティ
ここでは、Web APIクライアント機能として利用可能なプロパティについて解説します。
キー名 | 区分 | 説明 |
|---|---|---|
apl.http.client.connectiontimeout | オプション | アプリケーションからHTTP(S)通信を行う際に、接続が確立するまでのタイムアウト時間を指定します。（単位は秒） ※デフォルトは「10」です。 |
apl.http.client.readtimeout | オプション | アプリケーションからHTTP(S)通信を行う際に、レスポンスのデータを読み込むときのタイムアウト時間を指定します。（単位は秒） ※デフォルトは「10」です。 |
apl.http.client.server.verification | オプション | アプリケーションからHTTPS通信を行う際に、サーバー証明書のCommon Nameと接続先ホスト名の比較を行うか指定します。falseを指定すると比較しません。 ※デフォルトは「true」です。 |
apl.http.client.linetrace.outputbody.safety | オプション | 回線トレースにリクエストとレスポンスのボディ内容の出力を行うかを指定します。 trueを指定すると出力します。 falseを指定した場合は出力しません。 ※デフォルトは「false」です。 ※ボディ内容に対してマスク処理は行われません。 ※レスポンスのボディ内容の出力は1MBまでとなり、1MBを超えた場合は1MB分出力された後に[MORE]の文言が出力されます。 |
B 設定例
ここでは、SAP S4/HANAへ接続する設定例について解説します。
SAP側にPOSTなどのリクエストを実施するための設定例であり、すべての環境での動作を保証するものではありません。接続するSAP側の仕様に合わせて、適切な設定をご検討ください。
B.1 CookieとX-CSRF-Tokenを使う
CookieとX-CSRF-Tokenを使う方式の場合は、本来実施するPOSTなどを行うWeb APIリクエストジョブの前に、CookieとX-CSRF-Tokenを取得するためのGETないしはHEADリクエストを行う必要があります。
そのためフローとしては、次図のように2つのWeb APIリクエストジョブが必要です。
1つ目のWeb APIリクエストジョブでは、GETないしはHEADリクエストを行い、そのレスポンスで得られるSet-CookieとX-CSRF-Tokenの値を後続ジョブで使うためにタスクへの出力を行います。また、フローでロードした時のデータファイルを後続のWeb APIリクエストに渡すため、タスク出力対象の項目には「入力データ」を指定します。
このとき、リクエストヘッダーに「X-CSRF-Token: fetch」を含める必要があります。
2つ目のWeb APIリクエストジョブでは、Set-CookieとX-CSRF-Tokenの値をリクエストヘッダーに含める必要があります。
B.2 X-Requested-Withを使う
X-Requested-Withを使う方式の場合には、事前にGETやHEADを実施する必要はありません。次図のように、目的のWeb APIリクエストジョブのみが必要です。
リクエストを実施するジョブに、「X-Requested-With: X」を含める必要があります。
