【温故知新】第8回「統合APサーバー(IWS)でかんたんにREST APIサービスを作ってみよう」

今回はIBM i OS標準機能で無償利用できる統合Webサービスサーバーを使ってRPG/COBOL等のプログラムをREST API呼出しするサンプルを作ってみたいと思います。

シナリオとしては、「これまで5250等のレガシーなユーザー環境で使用しているRPG、COBOLプログラムやデータベースがある。このレガシー資産を無修正（または小改修）でAPI化し、ブラウザー、スマホ、クラウドサービス等から利用しDX化を実現する」というものです。（図1）
DX化、サービス対応などは現在大変一般的なテーマだと思われ、IBM i でも取り組まれているお客様がとても増えています。APIと言っても非常に簡単に始めることができる、という事を実感いただければと思います。

▲図1. IBM i REST API化シナリオ

全体図は次のようになります。

▲図2. サンプルREST APIコール環境の全体図

サンプル環境の構成

図2の環境は、以下のように作成しています。

IBM i 7.4 または7.5
図2① 物理ファイル QEOLの得意先マスターをベースにしています。
図2② バッチ型ILE RPGプログラム　QEOLにもある得意先照会プログラムをベースにバッチ型にしています。(後段にソースを掲載しています)
図2③ 統合APサーバーが使用可能なライセンスプログラム(下記)が導入済みであること
IBM HTTP Server for i (5770-DG1)
5770JV1 JAVA SE 8 64 BIT 　など各々のIBM i OSバージョンで該当するJavaバージョン
5770TC1 IBM TCP/IP CONNECTIVITY UTILITIES FOR I
5770SS1 option 30 of operating system
5770SS1 option 33 of operating system
5770SS1 option 12 of operating system
図2④ 統合アプリケーションサーバーは今回新規に作成し、②のILE RPGを呼び出すサービス定義をデプロイします。
図2⑤ ILE RPGプログラム呼出しサービスをデプロイします。

ではそれぞれのコンポーネントを見ていきましょう。

① 物理ファイル（テーブル）：得意先マスター TOKMSP

RPGが処理するデータベースファイルです。RPGからアクセスされますので一般に特別な考慮は無いと思われます。

得意先マスター：TOKMSP

CRTPFで作成したTOKMSPから逆引きで作成（ACS のデータベース->スキーマで生成）したDDLです。

--  SQLの生成 
--  バージョン:                    V7R5M0 220415 
--  生成:               24/05/17 16:34:44 
--  リレーショナル・データベース:        IBMI75 
--  規格オプション:           Db2 for i 
CREATE TABLE WESBDEMO.TOKMSP ( 
--  SQL150B   10   WESBDEMOのテーブルTOKMSP中のREUSEDLT(*NO)は無視されます。 
 TKBANG CHAR(5) CCSID 1027 NOT NULL DEFAULT '' , 
 TKNAKN CHAR(20) CCSID 1027 NOT NULL DEFAULT '' , 
 TKNAKJ CHAR(20) CCSID 5035 NOT NULL DEFAULT '' , 
 TKADR1 CHAR(20) CCSID 5035 NOT NULL DEFAULT '' , 
 TKADR2 CHAR(20) CCSID 5035 NOT NULL DEFAULT '' , 
 TKTIKU CHAR(2) CCSID 1027 NOT NULL DEFAULT '' , 
 TKPOST CHAR(6) CCSID 1027 NOT NULL DEFAULT '' , 
 TKTELE CHAR(13) CCSID 1027 NOT NULL DEFAULT '' , 
 TKGURI DECIMAL(9, 0) NOT NULL DEFAULT 0 , 
 TKNURI DECIMAL(9, 0) NOT NULL DEFAULT 0 , 
 TKZURI DECIMAL(9, 0) NOT NULL DEFAULT 0 , 
 TKUZAN DECIMAL(9, 0) NOT NULL DEFAULT 0 , 
 TKGEND DECIMAL(9, 0) NOT NULL DEFAULT 0 , 
 TKNYUK DECIMAL(6, 0) NOT NULL DEFAULT 0 , 
 TKSIME CHAR(1) CCSID 1027 NOT NULL DEFAULT '' , 
 PRIMARY KEY( TKBANG ) )   
   
 RCDFMT TOKMSR     ; 
  
LABEL ON TABLE WESBDEMO.TOKMSP 
 IS 'EOL/400得意先マスター物理ファイル' ; 
  
LABEL ON COLUMN WESBDEMO.TOKMSP 
( TKBANG IS '得意先            番号' , 
 TKNAKN IS '得意先            仮名' , 
 TKNAKJ IS '得意先            漢字' , 
 TKADR1 IS '住所１' , 
 TKADR2 IS '住所２' , 
 TKTIKU IS '地区              コード' , 
 TKPOST IS '郵便番号' , 
 TKTELE IS '電話番号' , 
 TKGURI IS '当月              売上高' , 
 TKNURI IS '当年              売上高' , 
 TKZURI IS '前年              売上高' , 
 TKUZAN IS '売掛金            残高' , 
 TKGEND IS '信用              限度額' , 
 TKNYUK IS '最終              入金日' , 
 TKSIME IS '締め日            コード' ) ; 
  
LABEL ON COLUMN WESBDEMO.TOKMSP 
( TKBANG TEXT IS '得意先 番号' , 
 TKNAKN TEXT IS '得意先 仮名' , 
 TKNAKJ TEXT IS '得意先 漢字' , 
 TKADR1 TEXT IS '住所１' , 
 TKADR2 TEXT IS '住所２' , 
 TKTIKU TEXT IS '地区 コード' , 
 TKPOST TEXT IS '郵便番号' , 
 TKTELE TEXT IS '電話番号' , 
 TKGURI TEXT IS '当月 売上高' , 
 TKNURI TEXT IS '当年 売上高' , 
 TKZURI TEXT IS '前年 売上高' , 
 TKUZAN TEXT IS '売掛金 残高' , 
 TKGEND TEXT IS '信用 限度額' , 
 TKNYUK TEXT IS '最終 入金日' , 
 TKSIME TEXT IS '締め日 コード' ) ; 
  
GRANT ALTER , DELETE , INDEX , INSERT , REFERENCES , SELECT , UPDATE   
ON WESBDEMO.TOKMSP TO GOMA WITH GRANT OPTION ; 
  
GRANT ALTER , DELETE , INDEX , INSERT , REFERENCES , SELECT , UPDATE   
ON WESBDEMO.TOKMSP TO PUBLIC WITH GRANT OPTION ;

※詳細なテーブル作成手順はこちらをご参照ください。
Db2 for i 既存のPF(テーブル)からSQL DDLを生成する手順
https://qiita.com/gomAnomalocaris/items/a98b05756fa8dffc394a

② サンプルILE RPGプログラム：得意先マスター照会

QEOLの得意先マスター照会をベースに作成したILE RPGバッチ型プログラムです。
IWS統合APサーバーから呼び出しされるRPG/COBOLはILE RPG/COBLである必要があります。従来、プログラムがILEでないRPG/COBOLの場合、CVTRPGSRCコマンド等でILE変換する（RPGの場合）か、元のRPGⅢ/COBOLをただ呼び出すだけのILE RPGまたはILE COBOLを新規作成し、このILEプログラムをIWS統合APサーバーに登録することでもできます。

ILE RPGのサンプルコードはこちらです。このプログラムをコンパイルしてREST APIから呼び出すプログラムを作成します。

******************データの始め********************************************
H DATEDIT(*YMD)                                                        
F* IPH110 * 得意先照会                                                  
FTOKMSP    IF   E           K DISK                                     
D*---------------------------------------------------------------------
D* INPUT DATA STRUCTURE                                                
DCUSTNO           S                   LIKE(TKBANG)                     
D*---------------------------------------------------------------------
D* OUTPUT DATA STRUCTURE                                               
D*                                                                     
DDETAIL           DS                                                   
DTKNAKJ                         20                                     
DTKADR1                         20                                     
DTKADR2                         20                                     
DTKTIKU                          2                                     
DTKPOST                          6                                     
DTKGEND                          9P 0                                  
DTKUZAN                          9P 0                                  
DSAGAKU                          9P 0                                  
D*---------------------------------------------------------------------
DDETAIL           DS                                                   
DTKNAKJ                         20                                     
DTKADR1                         20                                     
DTKADR2                         20                                     
DTKTIKU                          2                                     
DTKPOST                          6                                     
DTKGEND                          9P 0                                  
DTKUZAN                          9P 0                                  
DSAGAKU                          9P 0                                  
D*---------------------------------------------------------------------
C     *ENTRY        PLIST                                              
C                   PARM                    CUSTNO            5        
C                   PARM                    DETAIL                     
C*得意先マスターの読み取り                                                  
C     CUSTNO        CHAIN     TOKMSP                             30    
C     *IN30         IFEQ      '0'                                      
C*差額計算                                                              
C     TKGEND        SUB       TKUZAN        SAGAKU                     
C                   ELSE                                               
C                   MOVE      'ERROR'       TKNAKJ                     
C     *ENTRY        PLIST                                              
C                   PARM                    CUSTNO            5        
C                   PARM                    DETAIL                     
C*得意先マスターの読み取り                                                  
C     CUSTNO        CHAIN     TOKMSP                             30    
C     *IN30         IFEQ      '0'                                      
C*差額計算                                                              
C     TKGEND        SUB       TKUZAN        SAGAKU                     
C                   ELSE                                               
C                   MOVE      'ERROR'       TKNAKJ                     
C                   ENDIF                                              
C                   SETON                                        LR    
C                   RETURN

※REST APIでコールするILE RPG/ILE COBOLをコンパイルする場合、以下のパラメーターを指定して、PCMLという定義ファイルを作成する必要があります。PCMLファイルは後述の画面10で使用します。

PCMLインターフェース情報　PGMINFO パラメーター
　生成：PCML
ストリームファイル名：PCMLファイルを生成するIFSパス：以下の例では/PCML/WESBDEMO/CUSTQRY3.PCML と指定

▲図3.

③ 統合アプリケーションサーバー(IWS)のインスタンスを作成する

初期状態ですと②の統合アプリケーションサーバーとそれに紐づくHTTPサーバーのインスタンスは存在しないので作成します。インスタンス作成はNavigator for i から Web Administration for i画面を開いて行います。(図4)

▲図4. Web Administration for i のリンク

Web Administration for iの画面で全てのサーバータブを開きます。
下記図5のWeb Serviceサーバーの作成をクリックします。

▲図5.

※ここでの注意点として、図5. のようにすでにサーバー上で使用済みのポート番号を調べておきます。この後の手順で作成する統合APサーバーでは、使用されていないポート番号を指定します。

以下の例では、ポート番号5000番台を指定します。
統合APサーバーとHTTPサーバーのインスタンス名（図5で表示されるサーバー名＝WRKACTJOBのジョブ名）を指定します。(図6)
ここでは　IWORLD_IWS　とします。指定したら次へボタンを押します。

▲図6.

HTTPサーバー、統合APサーバーで使用するポートを指定します(図7)。
図7. の個々のポート番号（5004, 5003, 5013）の指定ルールは特にありませんが、ここではデフォルトで割振りされるポート番号に準じて設定しています。

▲図7.

図6. の後に表示される次のパネルはすべてデフォルトのまま　次へ　ボタンを押します。
サーバーのサブシステムの指定 – ステップ 3 / 5
サーバーのユーザー ID の指定 – ステップ 4 / 5

要約 – ステップ 5 / 5 の画面が表示されたら、これまで指定した内容が間違いない事を確認して、完了ボタンを押します。
すると指定に従ってHTTPサーバーと統合APサーバーのインスタンス作成が開始されます。(図8)

図8で　再表示ボタンを押すと状況が更新されます。

▲図8.

しばらく放置すると最終的に図9. のように作成されたAPサーバーの管理画面に遷移します。もしこの画面が出ない場合は、画面上のApplication Server タブをクリックして、サーバーのプルダウンから上記で作成したサーバー名を選択してください。

▲図9.

サーバーステータスが実行中になっています。以上で③のインスタンスは作成されました。

④ ILE RPGプログラム呼出しサービスをデプロイする

図9.で新規サービスの配置　をクリックするとサービスデプロイ用のウィザードが開始されます。(図10)

▲図10.

図10.では以下を指定します。
Webサービス・タイプの指定： REST REST APIで呼び出すことを指定
プログラム・オブジェクトのパス： ②で作成したILE RPGのプログラムオブジェクト名を指定します。統合APサーバーはJAVAアプリケーションですので、ライブラリー形式でなく、IFS形式でオブジェクト名を指定する必要がある点にご注意ください。

図10.のように /QSYS.LIB/WESBDEMO.LIB/CUSTQRY3.PGM というように入力します。WESBDEMO.LIB のようにILEプログラムが存在するライブラリー名を入力して参照ボタンを押すと、検索ウィンドウが表示され、そこから選択・入力できます。
次へボタンを押します。

※参考：ちなみに図10.の画面で、WebサービスとしてのSQL を選択すると、RPGではなく、Db2 for i に投入するSQL文を記述する画面に遷移します。RPGプログラムを使わずにSQL文をREST APIで外部コールするようにもできます。
次へボタンを押します。図11.が表示されます。

▲図11.

図11.ではIEL RPG/COBOLをコンパイルした際に生成したPCMLファイル名を指定します。
※PCMLファイルの中には、REST API（統合APサーバー）がILE RPG/COBOLを呼び出す際のパラメーター情報が記述されています。ご興味のある方はPCMLファイルをIBM i 上のEDTFコマンドやWINDOWS等にダウンロードしてエディターで開いてみてください。
次へボタンを押します。

▲図12.

図12.ではデプロイするサービスの名前を指定します。この名前はWeb Administration for i 画面など管理系で使用するだけで、実行ユーザーからは見えません。任意の名前を指定します。
次へボタンを押します。

以下の画面はすべて何も変更せずデフォルトのまま次へボタンを押します。
セキュリティー制約の指定 – ステップ 4 / 11

▲図13.

図13.はILE RPGの呼出しパラメーター指定画面です。この情報はPCMLファイルから読み取られたILE RPGの呼出しパラメーターです。使用法の入出力、出力をパラメーターごとに正しく修正します。例ではCUSTNOはREST APIで外部から取得する顧客番等で、IBM iから外部への返しにも含まれるので入出力、DETAILは得意先マスターの検索結果フィールド（複数）が含まれる配列で出力のみ使用、となります。
次へボタンを押します。

ILE プロシージャー情報の指定 – ステップ 6 / 11の画面はそのまま次へボタンを押します。

▲図14.

図14. ではREST APIから呼出しする際のURLやパラメーター受け渡しについての設定を行います。例での指定個所は以下になります。

HTTP要求メソッド	ILE RPGを呼び出すHTTPメソッドを指定。例ではGET。ほかにPOST, PUT, DELETE, PATCHが指定可能
メソッドのURIパス・テンプレート	REST API呼び出し側からのパラメーターの指定。ここでは、最下部の入力パラメーター1つ（CUSTNO）をCUSTNOという名前で受け取るための指定
入力パラメーター・マッピング	CUSTNOパラメーターをどのようにREST APIでパラメーター指定するか。ここではパスパラメーター（*PATH_PARAM）としており、REST APIのURLの最後にパラメーターを指定する方法としています。またその際のパラメーター名はCUSTNOと指定しています。URLパスパラメーター以外にもクッキーやヘッダーその他でのパラメーター受け渡しもできます。

次へボタンを押します。以下の画面は何も変更せずデフォルトのまま次へボタンを押します。
このサービスのユーザー ID を指定 – ステップ 8 / 11

▲図15.

図15. ではILE RPGプログラム実行に必要なライブラリーを追加します。例ではILE RPGプログラムの存在場所であるWESBDEMOが自動追加されています。
次へボタンを押します。

▲図16.

REST APIの呼び出し元に返す情報を選択します。ここでは上記のように選択しています。
次へボタンを押すとここまでの確認画面が出ます。間違いが無いか確認して、完了ボタンを押します。そうするとサービスのデプロイが開始されます。
下記のようにデプロイ中の画面に遷移します。デプロイが完了すると状況が実行中に変わります。

▲図17.

デプロイが完了して、状況が実行中になったら、デプロイした行（例ではCUSTQRY3）をクリックすると、ボタンが表示されます。
プロパティボタンを押します。

▲図18.

デプロイしたサービスの情報が表示されます。
ベース・リソースURL　というのがブラウザーその他REST APIから指定するURLの基本になります。例では下記になっています。
http://ibmi75:5013/web/services/CUSTQRY3

▲図19.

以上でサービスのデプロイも完了しました。
それではREST APIをつかってILE RPGをコールしてみましょう。

⑤ ILE RPGプログラム呼出しサービスをデプロイする

ここではWindowsのブラウザーから④で設定したベース・リソースURLを入力します。URLの最後にパラメーターCUSTNO（例では文字列5桁）を/01010 のように入力します。
すると下記のようにILE RPGが検索したDb2 for i 得意先マスターの検索結果が返されます。
ブラウザーの仕様によっては下記のように表形式的に見やすく返すものもあります。(例はfirefoxです。)

▲図20.

以上のように設定は比較的簡単だと思います。ILE RPGのバッチプログラムさえあれば様々なプログラムをAPIサービスとして公開し、モバイルや社外サービスに接続する事ができます。ぜひ皆様もお試しください。

筆者

日本アイ・ビー・エム株式会社
IBM Power Technical Sales　佐々木幹雄

多数の執筆記事を、iWorldに寄稿中。