10.1 Web APIクライアント機能の概要
ここでは、ACMS CloudのWeb APIクライアント機能の概要について説明します。
ACMS Cloudの概要の他、Web APIクライアントのプロトコルの詳細について学びたい場合は、以下のリンクをご参照ください。
https://community.dal.co.jp/s/article/protocol-webapi-client
10.1.1 Web APIクライアント機能とは
Web APIについて厳密な定義はありませんが、一般的にはHTTPというプロトコルを用いて異なるシステムに対する処理の呼び出しを実行するインターフェイスのことを指します。
ACMS CloudのWeb APIクライアント機能はこれに則ります。別のシステムに対してHTTP経由で処理の呼び出しを行い、その結果を取得する機能です。
ACMS CloudではWeb APIクライアント機能をアプリケーションとして実装しています。一回のWeb APIリクエストを一つのアプリケーションとして定義し、フローの中でそのアプリケーションを使うようにします。たとえば、基幹システムから受け取った情報を元にWeb APIのリクエストを実施し、そのレスポンスを元に別の基幹システムの処理を呼び出したり、ほかのWeb APIを続けて呼び出したりするなど、業務要件に合わせて柔軟に組み合わせることができます。
SAP S4/HANAのOData APIと組み合わせることで、次のような処理の流れを実現できます。赤枠の箇所が本機能の対象領域です。
発注書をEDIで受信した後に、SAPに対して受注伝票を登録するPOSTリクエストを実施します。出荷の段階では、出荷伝票をSAP側にGETリクエストで照会し、社内の別システムに出荷を依頼します。その結果をSAP側にPATCHリクエストで反映する流れを想定しています。
10.1.2 リクエストの管理
ACMS Cloudが通信やアプリケーションを実行する際には、「タスク」という形で実施した結果を記録します。送受信を実施した履歴管理をするとともに、二重送信の防止などを実現しています。
Web APIクライアント機能でもこれは同様です。Web APIクライアントのアプリケーションを実行するごとにタスクを作成し、そのリクエストの成否を記録します。
通信障害が発生したときなどのリクエストの再実行や、取り消しは、このタスクから実施できます。
10.1.3 サポート対象のWeb API
詳細は10.2仕様を参照してください。
10.2 仕様
ここでは、Web APIクライアント機能の仕様について解説します。ここに挙げた仕様の範囲で、Web APIサービスに接続できます。
10.2.1 HTTPメッセージの構成
Web APIクライアント機能は、HTTPプロトコルを用いてWeb APIサービスに接続をします。
HTTPのリクエストは次図のような構成を取ります。Web APIクライアント機能のアプリケーションが動作する際には、各種設定や実行時のパラメーター、入力データからこのようなリクエストを作成し、Web APIサービスに送信します。
これに対してサーバーからは次図のようなレスポンスが返却されます。
このレスポンスの内容を元に、リクエストが成功したかどうかを判断します。また、レスポンスヘッダーやレスポンスボディの内容を後続ジョブに引き継ぎます。
10.2.2 リクエストの構成要素
リクエストの構成要素を、Web APIクライアント機能がどのように扱うのか説明します。
10.2.2.1 HTTPバージョン
HTTPバージョンは、1.1、2のみをサポートします。それ以外のバージョンでのリクエストはできません。
10.2.2.2 メソッド
HTTP/1.1、HTTP/2に定義された次のメソッドと、拡張されたメソッド（PATCHやMERGEなど）を使用できます。
- GET
- HEAD
- POST
- PUT
- DELETE
- OPTIONS
- TRACE
なお、HTTP/1.1、HTTP/2ではCONNECTというメソッドも定義されていますが、プロキシ経由での接続に用いるものであるため本機能には指定できません。
10.2.2.3 URL
接続先を表すURLには、スキーム（http://かhttps://）やホスト名、ポート番号、パス、URLパラメーター、フラグメントを指定できます。日本語などの表現も、事前にエンコードすることなく用いることができます。
URLのパスやURLパラメーター、フラグメントには、固定値かマクロを用いることができます。マクロを用いることで、実行時に更新対象とするリソースを切り替えることや、照会対象の検索条件を変更することができます。
なお、OPTIONSメソッドに利用される *（サーバー全体を表す指示子）については指定できません。
スキームにhttpsを指定（TLS化）することで、通信経路を暗号化し、接続先と安全な通信を実施できます。詳細は「21 新規接続先を追加する（Web APIクライアント）」の「21.1.2 PKI系マスター情報の作成（任意）」を参照してください。
10.2.2.4 リクエストヘッダー
接続先Web APIサービスの仕様に合わせて、リクエストヘッダーを自由に追加できます。ヘッダーの値にマクロを用いることで、実行時にヘッダーの内容を変更することもできます。
次に挙げるものはWeb APIクライアント機能がリクエストヘッダーに追加します。
ヘッダー名 | 説明 |
|---|---|
Host | 接続先ベースURLの値から自動で設定します。 |
Connection | closeを固定で設定します。 |
User-Agent | 利用者が追加しなかった場合に、「ACMS Cloud」を設定します。 |
Accept | 利用者が追加しなかった場合に、「application/octet-stream」を設定します。 |
Accept-Encoding | 利用者が追加しなかった場合に、「gzip」を設定します。 Rangeが追加されている場合には、本ヘッダーは設定されません。 |
10.2.2.5 リクエストボディ
リクエストに用いるボディの内容は、フローにジョブとして定義されたときの前段ジョブから渡されたデータを用います。
データのフォーマットや文字コードをシステム上で正確に自動判別できないため、ボディを用いる場合にはContent-Typeヘッダーを指定する必要があります。指定されていない場合には、「application/octet-stream」を設定してリクエストします。
なお、リクエストメソッドがGETやHEADの場合は、ボディに値をセットできません。
10.2.3 レスポンスの構成要素
レスポンスの構成要素を、Web APIクライアント機能がどのように扱うのか説明します。
レスポンスの内容は、リクエストが成功したかどうかの判定と、リクエスト結果の記録のために使用します。
構成要素 | 判定に利用できるかどうか | タスクへの記録 |
|---|---|---|
ステータスコード | ○ | 出力パラメーターとして記録 |
理由(reason-phrase) | × | 出力パラメーターとして記録 |
レスポンスヘッダー | ○ | 出力パラメーターとして記録 |
レスポンスボディ | ○ | 出力データとして記録 |
10.2.3.1 リクエストの成否判定
多くのWeb APIサービスでは、リクエストに成功すると200番台のステータスコードがレスポンスされ、失敗した場合には400番台や500番台がレスポンスされます。
Web APIクライアント機能では、レスポンスのステータスコードでリクエストが成功したかどうかを判別します。200番台がレスポンスされたときにリクエストを正常として扱います。それ以外のステータスコードの場合は即時障害となります。なお、Web APIサーバー側のトラブルやネットワークの切断などにより、ACMS Cloudがレスポンスを受け取れないことがあります。そのような場合には一時障害として扱います。
Web APIサービス側のレスポンス仕様によっては、「200番台でも障害としたい」ケースや「400番台でも正常としたい」などのケースが考えられます。そのような場合には成否判定条件を追加することで対応が可能です。
成否判定条件の詳細については「21 新規接続先を追加する（Web APIクライアント）」の「21.2.1レスポンスの成否判定と終了状態の結びつけ」を参照してください。
10.2.4 認証方式
接続先のWeb APIサービスによっては、リクエストを実施する際に認証を必要とする場合があります。
ACMS Cloudでは次の認証方式に対応しています。
認証方式 | 説明 |
|---|---|
認証なし | 認証をせずに利用できるWeb APIにリクエストを行う場合に指定します。 |
Basic認証 | HTTPリクエスト時に、Basic認証を必要とするWeb APIにリクエストを行う場合に指定します。 BASE64にエンコードする際の文字コードはUTF-8です。 |
APIキー認証 | HTTPリクエスト時に、接続先が指定するリクエストヘッダーやURLパラメーターを含める必要があるWeb APIにリクエストを行う場合に指定します。 |
クライアント証明書による認証 | TLS接続時に、事前に登録したキーペアからクライアント証明書を送付する必要があるWeb APIにリクエストを行う場合に指定します。 |
OAuth 2.0 | HTTPリクエスト時に、OAuth 2.0の認可サーバーから発行されたアクセストークンを必要とするWeb APIにリクエストを行う場合に指定します。 |
10.2.5 Cookieの取り扱い
Cookieにはセキュリティ上重要な情報が含まれている可能性があるため、初期状態ではタスクに記録しません。
しかしWeb APIサービスの中には、Cookieに含まれるセッション情報を元にリクエストを受け付けるかどうかを制御することがあります。
ACMS Cloudでは、アプリケーションの設定でCookieをタスクに出力するか選べます。前段ジョブでCookieをタスクに出力し、後続ジョブでそのCookieの値を用いて処理をすることができます。
10.2.6 出力パラメーターの利用
前段ジョブでリクエストをした際のレスポンスヘッダーの値を必要とする場合があります。たとえばSet-Cookieの値やX-CSRF-Tokenなどがあります。
リクエストおよびレスポンスヘッダーの値は、タスクの出力パラメーターに記録されます。この値を用いることで、前段ジョブの結果を後続ジョブで使用できます。
タスクに記録する際の出力パラメーターの名称は次の通りです。
- HTTPリクエストヘッダーは「_apl_http_request_headers_」の接頭辞で始まる
- HTTPレスポンスヘッダーは「_apl_http_response_headers_」の接頭辞で始まる
- ヘッダー名を以下ルールで変換し、接頭辞と結合する
- すべて小文字にする
- 英数字以外の文字は、半角のアンダースコアにする
たとえばレスポンスヘッダーに設定されるSet-Cookieの場合は、「_apl_http_response_headers_set_cookie」として出力パラメーターに記録されます。
■同じヘッダー名がある場合の取り扱い
同一名称のヘッダーが複数存在する場合は、出力パラメーターには「,」区切りで結合した値を出力します。CookieとSet-Cookieに限っては、「;」区切りで結合した値を出力します。
■レスポンスヘッダーにContent-Dispositionがある場合の取り扱い
レスポンスヘッダーのContent-Dispositionはdisposition-type, disposition-parmに分解し、出力パラメーターに記録します。Content-Disposition, disposition-parmの分解成否も同時に出力していますので、後続ジョブで利用する際の判断材料として利用してください。
出力パラメーターキー | 設定内容 |
|---|---|
_apl_http_response_headers_content_disposition_result | Content-Disposition内容の分解成否を出力します。 |
_apl_http_response_headers_content_disposition_type | disposition-typeの内容を出力します。 |
_apl_http_response_headers_content_disposition_parm_[token] | disposition-parmの内容を出力します。ext-parameter形式の場合はcharsetでデコードした結果を出力します。 |
_apl_http_response_headers_content_disposition_parm_[token]_result | disposition-parmの分解成否を出力します。 |
_apl_http_response_headers_content_disposition_parm_[token]_language | ext-parameter形式で指定されている場合にlanguage内容を出力します。ext-parameter形式でない場合は出力されません。 |
disposition-type, disposition-parm等についてはRFC 6266, RFC 5987を参照してください。
[token]: disposition-parmのキーを設定します。上記のとおり、全て小文字、英数字以外はアンダースコアへと変換されます。例えば、Content-Disposition: inline; filename*=UTF-8’ja’abc.txtの場合、[token]の値はfilename_となります。disposition-parmをキーと、値に分解出来ない場合、[token]を含むパラメーターは出力されません。
10.2.7 リダイレクト処理
HTTPのリクエストを実施した際に、サーバー側からリダイレクトの指示が返ってくることがあります。
本機能で対応しているのは、次に挙げるステータスコードとLocationヘッダーで指示された場合のみであり、HTMLのmetaタグやJavaScriptでのリダイレクトには対応していません。
- 301
- 302
- 303
- 307
- 308
10.2.8 タイムアウト処理
HTTPのリクエストを実施した際に、ネットワークや接続先サーバーの問題で遅延することがあります。このようなときにレスポンスを待たないようにするため、タイムアウト処理が行われます。
タイミング | 説明 |
|---|---|
接続タイムアウト | 接続先のWeb APIサービスにコネクションが確立するまでの時間を監視します。デフォルトは10秒でタイムアウトします。 「apl.http.client.connectiontimeout」プロパティでタイムアウト時間を変更できます。 |
レスポンスタイムアウト | 接続先のWeb APIサービスにリクエストを送り、そのレスポンスのデータを読み込むときの時間を監視します。デフォルトは10秒でタイムアウトします。 「apl.http.client.readtimeout」プロパティでタイムアウト時間を変更できます。 |
実行監視時間 | アプリケーションの実行時間を監視し、指定時間を超えたときに強制停止させることができます。 リクエスト開始からレスポンス終了までの時間が決められているようなケースで用いることができます。 |
10.2.9 マルチパート処理
データファイルそのものをリクエストで送信したり、レスポンスで受信したりするような場合に、マルチパート形式を用いることがあります。
本機能ではマルチパート部の作成や解析を容易に行えるようにします。
次の制約があります。
- multipart/form-data形式のみの対応
- リクエストのみの対応（レスポンスは個別のパート情報ではなく、ボディ全体を受け取る）