【はじめてのInterSystems IRIS】Interoperability（相互運用性）：コンポーネントの作成（ビジネス・オペレーション）

この記事はこちらの投稿の続きの内容です。

前回の記事では、コンポーネント間のデータ送受信に使用される メッセージ について、作成するときの考え方や定義方法を確認しました。

今回の記事では、コンポーネントの作成方法の中から、ビジネス・オペレーションの作成について解説します。

• プロダクション
• メッセージ（前回の記事）
• コンポーネント
  • ビジネス・サービス
  • ビジネス・プロセス
  • ビジネス・オペレーション

早速サンプルを参照しながらコードを確認します。

メモ：BSはビジネス・サービス、BPはビジネス・プロセス、BOはビジネス・オペレーションの略です。

ビジネス・サービスとビジネス・オペレーションはスクリプトの記述があるため、VSCode または スタジオで作成します。ビジネス・プロセスは管理ポータルでも作成できます（VSCodeの使い方については、こちらの記事をご参照ください）。

作成順は特にありませんが、今回のサンプルで考えると、接続先の外部サイトは公開サイトであるためすぐに利用できます。こういった場合ビジネス・オペレーションから作成し始めるとテストが簡単に行えて便利です。

コンポーネント作成後のテストですが、ビジネス・プロセスとビジネス・オペレーションについては、プロダクションにテスト画面が用意されています。
ただ、本番環境で誤ってテストしないように、プロダクション定義のデフォルト設定でテストは無効化されています。

プロダクションで「テスト使用可」とするかどうかの設定方法は、以下の通りです（サンプルプロダクションは予め「テスト使用可」に設定しています）。

1)　ビジネス・オペレーション

サンプルでは、2種類のビジネス・オペレーションを用意しています。

1つは、REST で外部の Web API に都市名を渡し、気象情報の取得を依頼するオペレーションで、もう1つは、InterSystems IRIS 内のデータベースへ気象情報と購入商品名を渡し更新処理を依頼するオペレーションです。

1)-1 REST ビジネス・オペレーション

REST で外部の Web API  を呼び出すオペレーションの作成から確認していきましょう 。
このオペレーションは、Start.Request メッセージが入力されると GetKion() メソッドが起動し、外部サイトへ問い合わせを行い、気象情報を Start.Response メッセージに格納し返送します.

コード詳細はこちらをご参照ください。

REST 用ビジネス・オペレーションを作成する場合は、EnsLib.REST.Operation を継承します。

Class Start.GetKionOperation Extends EnsLib.REST.Operation

このクラスの継承により HTTP メソッドに合わせた IRIS 内の以下メソッドが提供されます。詳細はドキュメントもご参照ください。 

• GetURL()— HTTP GET オペレーションで使用します。
• PostURL()— HTTP POST オペレーションで使用します。
• PutURL()— HTTP PUT オペレーションをで使用します。
• DeleteURL()— HTTP DELETE オペレーションで使用します。

REST の場合、アダプタは EnsLib.HTTP.OutboundAdapter を使用します。アダプタ名を例のように ADAPTER パラメータと Adapter プロパティに設定します。

また INVOCATION パラメータは Queue を設定します。

Parameter ADAPTER = "EnsLib.HTTP.OutboundAdapter";
Property Adapter As EnsLib.HTTP.OutboundAdapter;
Parameter INVOCATION = "Queue";

接続先の OpenWeather の API は実行時に各自で入手する API Key の指定が必要になります。環境に合わせて設定値が変動するような項目は、プロダクションの設定項目として表示させる方法があります。

手順は以下の通りです。

1. プロパティを定義する
2. SETTINGSパラメータに作成したプロパティ名を指定する（複数ある場合はカンマで区切って指定します）。 任意でカテゴリも指定できます（プロパティ名:カテゴリ名 で指定します）。

コード例は以下の通りです。

/// APIキーを指定します
Property appid As %String;
Parameter SETTINGS = "appid:OpenWeatherMap";

プロダクション設定画面では以下のように表示されます。また、プロパティ定義の直前の行に記載した説明文は、図のようにプロダクション設定画面にも表示されます。

次に、ビジネス・オペレーションにとって大事な設定である、メッセージマップについて確認します。

上記定義は、Start.Request メッセージが送信されると、GetKion()メソッドが動作するように定義されています。

GetKion() メソッドでは、入力情報として渡される要求メッセージの Area プロパティから都市名が取得できます。
この都市名を外部の Web API が公開している URL のパラメータに設定し呼び出せば、気象情報が取得できます。

なお、HTTP サーバや URL の設定は管理ポータルのプロダクション画面で設定します。設定内容を取得するには、HTTP アウトバウンドアダプタから提供される Adapter プロパティを使用します。

例）　URLの指定の場合は、 ..Adapter.URL

REST 用ビジネス・オペレーションが提供する GetURL() メソッドを使用して、外部サイトを呼び出します。第1引数に実行したい URL（＝都市名など必要なパラメータに指定した URL）、第2引数に参照渡しで引数を用意し HTTP 応答を受け取ります。

HTTP 応答にはJSON 形式で気象情報が格納されるので、応答メッセージ（＝pResponse）に情報を登録したらオペレーションは完成です。

作成したメソッドの第 2 引数には、参照渡しで応答メッセージクラス名が指定されています。

Method GetKion(pRequest As Start.Request, Output pResponse As Start.Response) As %Status

呼び出し元に応答メッセージを返す場合は、応答メッセージのインスタンスを生成し、第 2 引数の変数（pResponse）に格納し、プロパティに必要な情報を設定します。

set pResponse=##class(Start.Response).%New()
set weatherinfo={}.%FromJSON(tHttpResponse.Data)
set pResponse.AreaDescription=weatherinfo.weather.%Get(0).description
set pResponse.KionMax=weatherinfo.main."temp_max"
set pResponse.KionMin=weatherinfo.main."temp_min"
set pResponse.Area=weatherinfo.name
//UTC時間なので日本時間にするために9時間（9*60*60）足すset unixEpochFormat=weatherinfo.dt+32400
set dt=$system.SQL.Functions.DATEADD("s",unixEpochFormat,"1970-01-01 00:00:00")
set pResponse.AreaPublicTime=dt

外部サイトからのHTTP応答がJSON形式で返送されるため、HTTP 応答で取得できたストリームを利用して、IRIS 内の JSON 操作に便利なダイナミックオブジェクトに変換しています。

set weatherinfo={}.%FromJSON(tHttpResponse.Data)

返送される JSON 文字列の例は以下の通りです。

最高気温、最低気温、天気　は以下のように取得できます。

set pResponse.KionMax=weatherinfo.main."temp_max"
set pResponse.KionMin=weatherinfo.main."temp_min"
set pResponse.AreaDescription=weatherinfo.weather.%Get(0).description

IRIS 内の JSON 操作について確認されたい場合は、こちらの記事やドキュメントもご参照ください。

それでは、天気情報をちゃんと取得できるかどうか、プロダクションのテストツールを使って確認しましょう。

プロダクション画面を開き（管理ポータル > [Interoperability] > [構成] > [プロダクション] ）Start.GetKionOperation をクリックし、[アクション]タブの「テスト」ボタンをクリックします。

Area に 都市名（那覇市、札幌市、長野市、新宿区　など）を指定して、「テストサービスを実行」ボタンをクリックします。
下にテスト結果が表示され、最高気温、最低気温、天気が表示されるのが確認できます。

続いて、トレース画面の使い方をご紹介します。

左画面で  などの横長の長方形を選択すると、右画面の情報が変わります。

システム統合の流れで送受信したメッセージは自動的にデータベースに保存されます。メッセージのトレース画面を使用すると、時系列でどのようなメッセージがどのコンポーネントに渡されたか、応答があったかどうか、など詳細に確認することができます。

また、エラーが発生した場合は、

「○から△のコンポーネントに□のメッセージを 送付中／受信中／受信後 にエラー発生」

がわかるように、エラーが発生した場所に赤いマークがつきます。もちろん、トレース以外にもイベントログページも用意しています。
（管理ポータル > [Interoperability] > [表示] > [イベントログ]）

続いて、データベースへ更新依頼を行うオペレーションを確認してみましょう。

1)-2 データベースへ更新依頼を行うビジネス・オペレーション

サンプルには Start.SQLInsertOperation と Start.InsertOperation の2種類のオペレーションの用意があります。

それぞれ、データベースの更新依頼を行うオペレーションですが、Start.SQLInsertOperation は、SQLアウトバウンドアダプタを利用していますが、Start.InsertOperation は、アダプタを使用していません。

両者の違いは、

SQL アウトバウンドアダプタを使用するオペレーションは、ODBC／JDBC接続でのアクセスを前提としているため、データベースの接続先をプロダクションの設定で切り替えることができます。

アダプタを使用しないオペレーションでは、DB更新対象はプロダクション構成から見える範囲のデータベースで、接続先の切り替えが発生しないことが前提となります。

IRIS にはデータベースが含まれているため、システム統合中の任意データの格納場所に IRIS 内データベースを使用できますが、数年後、システム構成が何らかの理由で変更となり、異なるサーバ上のデータベースへ接続する必要が出てきた場合、アダプタを使用しないオペレーションをそのまま継続利用することはできません。

反対に、SQL アウトバウンドアダプタを使用するオペレーションは、接続先指定を変えることで処理内容に変更が無ければそのまま運用できます（実行する SQL 文に問題がなければ、異なる製品のデータベースにも接続できます）。

システム統合の中では、外部システムの都合で接続情報が変更となるケースも考えられるため、変更に柔軟に対応できるような設計にしておくことが重要です。そのため、外部接続に対応するコンポーネントは 疎結合 で作成することを推奨しています。

とはいえ、将来構成に変更がなければ、わざわざ ODBC／JDBC 接続を使用しなくても IRIS 内データベースにアクセスできますので、利用用途に合わせアダプタを使用する／しないをご選択いただけます。

それでは順番に、アダプタを使用する Start.SQLInsertOperation のコードを確認しましょう。

サンプルが使用しているアダプタは SQL アウトバウンドアダプタで、データベースに対して SQL文 の実行を依頼できるアダプタです。
アダプタが異なると提供されるメソッドも異なります。アダプタから提供されるメソッド詳細についてはドキュメントをご参照ください。

続いて、アダプタを使用しない Start.InsertOperation のコードを確認しましょう。

アダプタを使用する／しないに関わらず、オペレーションのメッセージマップとメソッド定義は必要です。アダプタを使用しない場合は、アダプタ用 Paramter と Property の定義は不要です。

アダプタを使用しないビジネス・オペレーション： Start.InsertOperation では、ObjectScript を利用してSQLを実行しています（コメント文はオブジェクト操作での更新処理です）。

更新対象データベースが IRIS から切り離されることが無ければ十分な実装といえます。

 アダプタを使用したオペレーションは、接続先に処理を依頼するための専用メソッドが提供されることがわかりました。また、アダプタを使用しないオペレーションも作成可能で自由にコードを記述できることが確認できました。

次の投稿では、天気情報取得用オペレーションとデータベース更新用オペレーションを順番を守って呼び出しを行うビジネス・プロセスの作り方について解説します。