【Oracle】Oracle Integration Cloudを使ってREST APIを実行してみる

Oracle Integration Cloud(OIC)を使って超簡単なIntegrationを作ってみます。
自分の練習用かつ備忘録の色が強いですが。




1.はじめに

OICについてはこちら等を参考にしてみてください。
なんなら私もよくわかっていません。
要するに、「とあるシステムAと別のシステムBを、GUIを駆使していい感じで繋げるよ」という代物のようです。
実際には両者はRESTやSOAP等によるAPIで待ち構える口を作ってくれている前提で、そのAPI同士を繋げてあげる仕組みです。
実運用では、OracleのSaaSアプリケーションやSalesforce等と連携するのが多いんでしょうが、とりあえず今回は無料のREST APIを接続先に据えてみます。




2.無料REST API

今回餌食になる協力してもらう無料REST APIは郵便番号検索のAPIです。
https://postcode.teraren.com/doc

上のHPに記載のあるExampleの例をcurlで実行してみます。
curl -i https://postcode.teraren.com/postcodes.json?s=1600023


HTTP/2 200
date: Tue, 05 Feb 2019 XX:XX:XX GMT
content-type: application/json; charset=utf-8
server: nginx/1.14.0 (Ubuntu)
vary: Accept-Encoding
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
x-download-options: noopen
x-permitted-cross-domain-policies: none
referrer-policy: strict-origin-when-cross-origin
access-control-allow-origin: *
access-control-request-method: *
etag: W/"84f6162e28b9a5122ad8c063dda91da2"
cache-control: max-age=0, private, must-revalidate
x-request-id: d1723122-2e17-43bc-8ecd-a6605f6d8cc6
x-runtime: 0.271327
vary: Accept-Language

[{"jis":"13104","old":"160  ","new":"1600023","prefecture_kana":"トウキョウト","city_kana":"シンジュクク","suburb_kana":"ニシシンジュク","prefecture":"東京都","city":"新宿区","suburb":"西新宿","is_separated_suburb":0,"is_koaza":0,"is_chome":1,"is_include_area":0,"status":0,"reason":0,"url":"https://postcode.teraren.com/postcodes/1600023.json"}]

↑のようなレスポンスが返ってきました。(時間部分等一部マスクしてあります)
パラメータsに郵便番号7桁を渡すとその住所がJSON形式で返却されるAPIのようです。
OICにIntegrationとして構築する際には赤太字の内容が重要になっています。
これは後で必要になるので忘れないでおきます。
(まあその時になったらまたcurl叩けばいいだけだが)

レスポンスのボディ部にあたる、下部の赤太字の部分を丸ごとコピーして、ローカルに「postcodes_response_sample.json」とでも名前を付けて保存します。
保存時の文字コードはpostcode.jsonの仕様に合わせてUTF-8にします。
これは後で使います。

なお、このAPIは「s」に7桁の郵便番号を渡すとそれに該当する住所がそのまま返ってくる他、キーワードを渡すと文字列検索もできます。
この場合、レスポンスは配列になります。
複数件ヒットした場合のレスポンスを想定して、例にもあるように「s=新宿」等も実行し、レスポンスを同様にjsonファイルに保存しておいてもいいかもしれません。




3.OICで接続定義をつくる

OICの管理コンソールUIに入って、ハンバーガーメニューから「接続」を選択・右上の「作成」ボタンを押します。
20190205_blog_OIC_IMG01.png

接続アダプタがいっぱいでてくるので、「REST」を選択します。
20190205_blog_OIC_IMG02.png

新規接続作成画面に遷移します。
名前と識別子が必須です。
後でわかるように適当に付けます。
「ロール」については「呼び出し」を選択します。
20190205_blog_OIC_IMG03.png

続いて「接続の構成」をクリックします。
20190205_blog_OIC_IMG04.png

いくつか入力する箇所がありますが、とりあえず以下の通り入力します。
20190205_blog_OIC_IMG05.png

項目設定値備考
接続タイプ REST APIベースURL
TLSバージョン TLSv1.2 2019年2月現在、PSOTCODES側は1.1でも通るみたいですが、最新にしておきます。
ちなみに2019年2月現在OICではTLS1.2までしか選べません。
接続URL https://postcode.teraren.com/ 2.で試したときにはhttps://postcode.teraren.com/postcodes.json?s=1600023というように
ドメイン配下のリソースURIを指定していますが、これは後で指定するので、ここではそこまで記述しません。
アウトバウンド接続の双方向SSL有効化L はい
アイデンティティ・キーストア・エイリアス名 (入力なし) よくわからんから無視。w


続いて「セキュリティの構成」をクリックします。
20190205_blog_OIC_IMG06.png

今回は無料で公開されてるREST APIを使うので、認証は必要ありません。なので「セキュリティポリシーなし」を選択します。
実運用だと「セキュリティポリシーなし」は稀でしょうね…
20190205_blog_OIC_IMG07.png

ここまで来たら一案上に戻って「テスト」を押します。
20190205_blog_OIC_IMG08.png

テストが問題なく動作したら「保存」を押します。
20190205_blog_OIC_IMG09.png

で、「閉じる」を押します。
接続の一覧画面に戻るので緑のレ点がついてるのを確認します。
これで接続定義は作成完了です。
20190205_blog_OIC_IMG10.png

同じ要領で今度は「トリガー」を作成します。
20190205_blog_OIC_IMG11.png

「トリガー」は「呼び出し」と違って「繋ぎ先」が存在しないので、定義として作成してしまえばそれで終了です。
「呼び出し」と違って設定画面も非常にシンプルになっています。
通知先のメールアドレスを設定しないならこれで完了です。
「テスト」(意味があるのかは不明だが)「保存」を押して「閉じる」を押します。
20190205_blog_OIC_IMG12.png




4.OICで統合定義をつくる

次にハンバーガーメニューの「統合」を押して統合定義作成メニューに遷移して、右上の「作成」ボタンをクリックします。
20190205_blog_OIC_IMG13.png

左上の「アプリケーション主導のオーケストレーション」を選択します
20190205_blog_OIC_IMG14.png

適当に名前つけて「作成」を押します。
20190205_blog_OIC_IMG15.png

統合定義作成キャンパスが表示されるので、右側の◎みたいなマークを押してさっきつくった「トリガー」を選択し、「開始」というボタンのそばにドラッグ&ドロップします。
20190205_blog_OIC_IMG16.png

20190205_blog_OIC_IMG17.png

トリガーの入力画面が表示されるのでいろいろ入力していきます。
20190205_blog_OIC_IMG18.png

項目備考
エンドポイントの名前 test_rest_trigger なんでもいいです
エンドポイントで何が行われるか (いらん) 実際には機能説明を記載するのだと思われます
エンドポイントの相対URI /test_rest_trigger これが、外からOICを呼び出すときの相対URIになります。
実際にはFQDNとOICのAPI用のコンテキストパスがくっついて、
その配下にこのURIで示されるリソースが設定される形です。
今回は最終的にpostcodes.jsonを呼び出しますが、
これは「呼び出し」のほうで設定するので、
入り口となるこの定義の名前はなんでもいいです。
エンドポイントのアクション GET これは呼び出し側に合わせる必要はないんでしょうが、
一応合わせてGETにしておきます。
エンドポイントのパラメータ追加 チェック有 最終的に呼び出し側に引き渡すため、
入り口のここでもパラメータを受け取れるようにします。
エンドポイントのレスポンス受信 チェック有 postcodes.jsonのレスポンスを受け取れるようにします。

右上の「次へ」を押します。
次はリクエストパラメータを設定します。
パラメータの内容はとりあえずpostcodes.jsonの仕様に合わせて「s」と「page」という2つのパラメータを用意しておきます。
20190205_blog_OIC_IMG19.png

右上の「次へ」を押します。
次はレスポンスを設定します。
20190205_blog_OIC_IMG20.png

「レスポンス・ペイロード書式を選択」で「JSONサンプル」を選択します。
するとサンプルを選択する箇所が表示されるので、2.の最後で保存した「postcodes_response_sample.json」を選択します。
これで、OICが自動でレスポンスの要素構成を判定してくれます。

ちなみに、JSONサンプルを選択した場合、OICのContent-Typeは内部的にapplication/jsonで固定されるようです。
なので、「レスポンスの文字列はJSON形式なんだけどContent-Typeはtext/plainなんだよなあ」みたいなREST APIと接続する場合、実行時に内部エラーが起きます(;´Д`)
自由にContent-Typeを指定することもできなくはなさそうなんですが、よくわからんのでいったん注意点として記載するだけにとどめておきます。

右上の「次へ」を押します。
最後にサマリーを確認して問題なければ右上の「完了」を押します。
20190205_blog_OIC_IMG21.png

トリガーの設定が完了し、キャンパスに戻ってきます。
以下のような表示になります。
20190205_blog_OIC_IMG22.png

続いて今度は「呼び出し」を設定します。
右側の◎みたいなマークを押して、先ほど作成した「呼び出し」の定義を選択し、さっき設置した「トリガー」と下にある「マップ先」というオブジェクトの間にドラッグ&ドロップします。
20190205_blog_OIC_IMG23.png

20190205_blog_OIC_IMG24.png

また似たような画面が表示されます。
20190205_blog_OIC_IMG25.png

項目備考
エンドポイントの名前 test_rest_invoke_to_postcodes なんでもいいです
エンドポイントで何が行われるか (いらん) 実際には機能説明を記載するのだと思われます
エンドポイントの相対URI /postcodes.json さっきの「トリガー」と異なり、
こっちは接続定義に「https://postcode.teraren.com/」まで定義してあるので、
そこから実際に呼び出すことになる相対URIを指定します。
呼び出したいのはhttps://postcode.teraren.com/postcodes.jsonなので、
ここでは「/postcodes.json」だけ指定します。

エンドポイントのアクション GET ここはpostcodesのAPI仕様に合わせる必要があります。
なので「GET」にします。
エンドポイントのパラメータ追加 チェック有 実際にpostcodesにリクエストパラメータを投げるために必要なのでチェックします。
エンドポイントのレスポンス受信 チェック有 postcodes.jsonのレスポンスを受け取れるようにします。

この後はトリガー設定時と同様なので省略していきます。
まずはリクエストパラメータ
20190205_blog_OIC_IMG26.png

次はレスポンス、同様に「JSONサンプル」→jsonファイルを指定します。
20190205_blog_OIC_IMG27.png

最後にサマリーを確認して「完了」します。
20190205_blog_OIC_IMG28.png

キャンパス画面に戻ってきます。
20190205_blog_OIC_IMG29.png

続いて2つある「マップ先」の設定をしていきます。
まず上のほうの、「トリガー」と「呼び出し」の間にある「マップ先」をクリックして、3つ出てくるアイコンのうち真ん中の鉛筆マーク(編集ボタン)をクリックします。
20190205_blog_OIC_IMG30.png

すると以下のような画面に遷移します。
20190205_blog_OIC_IMG31.png

左側が「トリガー」で設定したリクエストパラメータで、右側にあるのが「呼び出し」で設定したリクエストパラメータです。
ここで「マッピング」という作業を行います。
「トリガー」と「呼び出し」のパラメータの「引き渡し」の定義をここで行うのです。
パラメータ名を同じにしたので、「s」と「s」を、「page」と「page」とをくっつけます。
左側の「s」をクリックし、右側の「s」もクリックし、両社が選択状態になったら、左側にある「マップ」というボタンを押します。
20190205_blog_OIC_IMG32.png

すると左側の「s」と右側の「s」が緑の線で繋がれたのが確認できます。
これでOICで受けるリクエストパラメータの「s」とpostcodesに流す「s」がつながった形になります。
右側の「マッピング」の項目にも、左側の「s」がマッピングされたことが表示されて確認できます。
20190205_blog_OIC_IMG33.png

同様に「page」も設定していきます。
20190205_blog_OIC_IMG34.png

今回はトリガー側のリクエストパラメータ名を最終的に呼び出すpostcodesのパラメータと同じ名前と個数にしたので同じように表示されていますが、例えばOICとしての入り口は「s」ではなく「keyword」などの名前にしておいて「s」とマッピングする設定や、OICとしては「s」しか受け取らない(「page」を受け取らない)で内部的に「page」の値を固定にして流す等の設定も可能です。
この辺はケースバイケースで個々の状況に応じて検討が必要になるんでしょうね。

マッピング設定が終わったら右上の「検証」ボタンを押します。
マッピング設定が有効であることを確認できます。
20190205_blog_OIC_IMG35.png

「閉じる」を押します。
キャンパス画面に戻ってきます。
1つ目のマッピングが設定し終えたことが確認できます。
20190205_blog_OIC_IMG36.png

続いて下のほうにあるマップ先も設定していきます。
20190205_blog_OIC_IMG37.png

今度はレスポンスのマッピングです。
レスポンスは、トリガーでも呼び出しでも、JSONサンプルを指定していたので、そのJSONサンプルからOICが自動で項目の分解をしてくれています。
トリガーと呼び出しで同じJSONファイルをサンプルで使ったのでやはり左側と右側で同じ項目名が並んでいます。
リクエストのときと同様、同名項目を選択してマッピングを行っていきます。
一通り設定終わったら「検証」し、問題ないことが確認出来たら「閉じる」で設定を反映します。
ちなみに、「topLevelArray」という要素もマッピングしないと、複数件ヒットした場合(s=新宿等の文字列検索した場合等)にエラーになりますので、忘れずにマッピングしておきます。
20190205_blog_OIC_IMG38.png

キャンパス画面に戻ります。
2つ目のマッピングも完了しました。
20190205_blog_OIC_IMG39.png

次にキャンパス右上のハンバーガーメニューを押して「トラッキング」を選択します。
20190205_blog_OIC_IMG40.png

トラッキングの設定画面が開きます。
左側にリクエストパラメータが表示され、右側にトラッキングの設定項目が表示されます。
ここでは「s」「page」をそれぞれ選んで、赤枠で囲った>ボタンを押して右側に設定します。
20190205_blog_OIC_IMG41.png

トラッキングは、後で統合定義の実行状況を追跡するのに必要な情報を設定する画面です。
最低一つはパラメータを指定しないといけません。
逆に言うと一つでも設定してればOKなので、今回のケースでいうと「s」か「page」のどっちかでいいんですが、とりあえず2つ設定しておきます。

これを設定するとまたキャンパスにもどるので、右上の「保存」ボタンを押して設定を反映させます。
20190205_blog_OIC_IMG42.png

統合定義の一覧画面に戻ってきました。
ここで、この統合定義を「アクティブ化」します。
赤枠で囲った部分をクリックします。
20190205_blog_OIC_IMG43.png

「統合のアクティブ化」に関する確認ウィンドウが表示されます。
特に何もなければそのまま右下の「アクティブ化」を押します。
20190205_blog_OIC_IMG44.png

なお、「Oracle Recommends」は、画像ではチェック外していますが、デフォルトはチェックついてるのでそのままでもいいです。
これは、マッピングの定義をするときに「お勧め」設定を選択できるのですが、そのための元情報に使わせるかどうかという設定項目のようです。
もっと具体的なケースで、「お勧め」設定が適切でなく、自身でマッピングを行った場合、それを「お勧め」として反映させるときにチェックを付けます。
デフォルトはチェック付きなのでOracle的にはマッピングの情報をいろいろ収集したいようですね。
今回のこの統合定義は、逆にOracleにとってノイズになりそうなので、というか正直この郵便番号検索APIを使う統合定義は俺以外使わない気がするので俺は外しておきました。w

アクティブ化が完了すると下のような表示になります。
20190205_blog_OIC_IMG45.png

統合定義の行にある歯車マークをクリックすると、吹き出しが上がります。
そこに~/metadataというURLが表示されています。
20190205_blog_OIC_IMG46.png

これが、この統合定義のusageになっています。
そのままクリックすると使い方ページがブラウザに表示されます。
「Endpoint URL」に、実際に外部からリクエストする場合のURLが表示されています。
パラメータ部は適切に与えてやる必要がありますが、基本的にはこのURLがOICの統合定義を実行するときのリクエストURLになります。
20190205_blog_OIC_IMG47.png

これでようやく準備完了です。





5.実行してみる

コマンドプロンプトやLinux系OSの端末を開いて、以下のようなコマンドを実行してみます。
[username]、[password]はクラウドアカウントにサインインするときのユーザー名とパスワードで置き換えてください。
curl -u [usrrname]:[password] -i [Endpoint URL]?s=1600023

HTTP/1.1 200 OK
Date: Tue, 05 Feb 2019 XX:XX:XX GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 457
Connection: keep-alive
X-ORACLE-DMS-ECID: cea18b4a-a67c-4863-b95a-2e07870c4c7f-0002b28b
X-ORACLE-ICS-INSTANCE-ID: 800001
X-ORACLE-DMS-RID: 0

[ {
  "jis" : "13104",
  "old" : "160  ",
  "new" : "1600023",
  "prefecture_kana" : "トウキョウト",
  "city_kana" : "シンジュクク",
  "suburb_kana" : "ニシシンジュク",
  "prefecture" : "東京都",
  "city" : "新宿区",
  "suburb" : "西新宿",
  "is_separated_suburb" : 0,
  "is_koaza" : 0,
  "is_chome" : 1,
  "is_include_area" : 0,
  "status" : 0,
  "reason" : 0,
  "url" : "https://postcode.teraren.com/postcodes/1600023.json"
} ]

改行されて見やすく整形せれてはいますが、2.項で実行したのと同じレスポンスが返ってきたのを確認できました。

OICの管理コンソールUIに戻って、メインのハンバーガーメニューからモニタリング>トラッキングを選択します。
20190205_blog_OIC_IMG48.png

実行履歴が表示されます。
20190205_blog_OIC_IMG49.png

エラーが発生していると赤く表示されます。
「s:1600023」の部分をクリックすると、先ほど作成した統合定義のキャンパスに入り、どこでエラーが起きたか等詳細に追跡することができます。





今回は、「一般公開されているREST APIにOICから接続する」というケースですが、接続の入り口が他システムやサービスからではなく、ただの普通のRESTの口になっているため、「一般公開されているRESTの手前に別の一般公開されている連絡口を設けた」形になっており、要するに不要な口が一つ増えてしまっています。
最終的にはpostcodesのAPIにリクエストするのは代わりないので、それなら冒頭2.で実施したように直接postcodesのAPIにリクエストしたほうが早いし、断然わかりやすいです。
冒頭述べたように、OICの本質は、「別システム同士をつなぐ」ことにあるはずなので、この例はOICの本質を生かし切れていない、というか完全に殺してしまっているのは間違いなく、その点においては悪い例であるといえるでしょう。
中間のマップ定義を、途中書いたように、「s」一つで受けて「page」を途中で足すとか、その辺の細工をするならまだわからなくもないですが、それだって単にpostcodesのリクエストURL叩くときにパラメータそう変えればいいだけですしねえ…
まあ、基本操作が学べたということで、とりえあえずOKとしておきます。


この記事へのコメント