Integration Tutorial (REST)

はじめに

目的

本ハンズオンでは、既存のREST APIに対して、Oracle Integration Cloud(以下、OIC)で新たなRESTエンドポイントを構成・公開するために、REST to RESTの連携フローを実装します。

このハンズオンを通じて以下のポイントを理解することができます。

なお本ハンズオンでは、既存のREST APIとして、OICが運用・管理用途で公開しているREST API(Integrationのメタデータを取得するAPI)を利用します。


最終構成

本ハンズオンの最終構成を以下に示します。

image2

完成版をエクスポートしたものはこちらにあります。


前提

OICでは運用・管理を目的としたREST APIを提供しており、本ハンズオンでは、その中のOICの統合のメタデータを取得するAPIを使用します。OICの運用・管理用のREST APIの一覧は、以下のドキュメントをご覧ください。

Integration Cloud

https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/index.html

Integration Cloud (User managed)

https://docs.oracle.com/en/cloud/paas/integration-cloud-um/rest-api-um/index.html

本ハンズオンを実施する前に、アクティブな統合を用意する必要があります。

動作確認を簡単にするため、REST APIを呼び出すためのツール(REST APIテストクライアント)を用意してください。

本ハンズオンでは、以下のツールを使用した手順を掲載していますが、既にREST APIテストクライアントをお持ちであれば、特にインストールする必要はありません。

ツール名:Advanced REST client

インストール方法

  1. Google Chromeを開き、以下のURLへアクセスします。 https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo
  2. Chromeに追加をクリックします。

    image3

  3. Google Chromeの右上にあるアプリをクリックします。

    image4

  4. ARCのアイコンをすると、Advanced REST Clientアプリを起動できます。

    image5

(オプション)この後の手順において、クライアント環境によってはネットワーク上のProxyの影響により、ARC Advanced REST ClientからのHTTPリクエストがタイムアウトになる場合があります。その場合は「ARC PROXY EXTENSION」を追加インストールしてみてください。

image6


接続の作成

RESTアダプタを使用して、REST接続を定義します。RESTアダプタでAPIのURLや認証情報を登録すると、REST APIへ接続できるようになります。

  1. OICのホーム画面でIntegrationsのページに移動します。

    image7

  2. メニューで接続をクリックします。

    image8

  3. 作成をクリックします。

    image10

  4. RESTアダプタを選択します。

    image11

  5. 次の接続情報を入力します。

    フィールド 入力値
    接続名 REST-OICAPI <user name>
    識別子

    入力不要

    Connection Nameから自動で導出されます: REST_OICAPI_<user name>

    接続ロール 設定不要(トリガーと呼出し)
  6. 作成 をクリックします。

    (オプション)電子メール・アドレス に管理者用の E-Mailアドレスを入力します。(例: admin@tenant.com)

  7. 接続の構成をクリックし、次の接続プロパティを設定します。

    フィールド 入力値
    接続タイプ REST APIベースURL
    TLSバージョン 設定不要
    接続URL

    https://OICのホスト名

    ブラウザのURLのホスト名をそのまま利用します

  8. セキュリティの構成 をクリックし、次の値を入力します。

    フィールド 入力値
    セキュリティ・ポリシー Basic認証
    Username OICのログイン・ユーザー
    Password OICのログイン・パスワード
  9. 接続できることを検証するため、テスト ボタンをクリックします。画面上部に “正常にテストされました。”のメッセージが表示され、インジケータが100%になっていれば、接続の構成は完了です。

    image12

  10. 保存をクリックして接続を保存し、閉じるをクリックして接続の編集画面を閉じます。

−−−−−−−−

連携フローの定義

OICの統合メタデータを取得

連携フローを開発するために、REST APIを呼び出した際のレスポンス・ペイロードを収集しておく必要があります。今回はOICの統合メタデータを取得するREST APIを利用しますので、このAPIのレスポンス・ペイロードを取得しておきます。

あわせて、OICが提供する運用向けREST APIの利用方法についても理解してください。

  1. メニューで統合をクリックします。

    image13

  2. 右のトグル・ボタンがチェック(緑色)されている統合を1つ(何でも良い)選び、統合名をクリックします。以下ではHello worldという統合を例に説明します。

    (オプション)もしチェックされてる統合が1つも無い(トグル・ボタンが全て灰色)場合はHello Worldのトグル・ボタンをクリックしアクティブ化してください。統合のアクティブ化ウインドウがポップアップするのでアクティブ化をクリックします。暫くするとトグル・ボタンが灰色から緑色に変わります。

    image14 image15 image16

  3. 画面右のメニューアイコンをクリック、プライマリ情報のリンクをクリックします。

    image17

  4. 識別子バージョン情報をメモしておきます。

    image18

  5. 閉じるをクリックします。

  6. REST APIテストクライアントを起動します(本ハンズオンでは、Advanced REST Clientを利用した手順を記載します)。

  7. Request URLに次の通りURIを入力します。

     https://OICホスト名/ic/api/integration/v1/integrations/{id}
    
    Name Value
    id

    <確認した統合の識別子>|<確認した統合のバージョン番号>

    例えば、識別子がHELLO_WORLD、バージョンが01.02.0000の場合は、idはHELLO_WORLD|01.02.0000

  8. SENDボタンを押すと、認証情報を求めるポップアップが現れます。下表の通り設定し、ACCEPTをクリックします。

    フィールド 入力値
    Username OICのログイン・ユーザー
    Password OICのログイン・パスワード

    image19

  9. レスポンスのペイロードをダウンロードし、JSONファイルとして保存しておきます。

    image20


統合の作成

  1. メニューで統合をクリックします。

    image21

  2. 作成をクリックし、ダイアログで基本ルーティングを選択します。

    image22

  3. 次の情報を入力して、作成をクリックします。

    フィールド 入力値
    統合にどのような名前を付けますか。(統合名) Get Integration Metadata <user name>
    識別子

    入力不要

    Integration Nameから自動的に導出されます:
    GET_INTEGRAT_METADATA_<USER NAME>

    バージョン

    入力不要

    デフォルト値を使用します: 01.00.0000

    この統合では何がおこなわれますか。(説明) 入力不要
    この統合はどのパッケージに属しますか。(パッケージ名) 入力不要
  4. 画面右側の接続一覧から、先ほど作成した接続を選択し、トリガーのドラッグ・アンド・ドロップへドラッグします。

    image23

  5. 基本情報の設定画面で次の通りに入力し次 >をクリックします。本演習では指示がないフィールドはデフォルトのままとしてください。

    フィールド 入力値
    エンドポイントにどのような名前を付けますか。 REST-Proxy
    このエンドポイントで何が行われますか。 任意の値
    エンドポイントの相対リソースURLは何ですか。 /integration-metadata
    エンドポイントでどのアクションを実行しますか。 GET
    このエンドポイントのパラメータを追加して確認 チェック
    このエンドポイントを構成してレスポンスを受信 チェック
  6. リクエスト・パラメータの設定画面で次のパラメータを追加し次 >をクリックします。

    名前 データ型
    id string
  7. レスポンス・ペイロード書式を選択にて、レスポンス・ペイロード・ファイルとしてJSONサンプルを選択します。サンプルの場所を指定、もしくはenter sample JSONが表示されるので、enter sample JSONの右にある <<<inline>>> をクリックして、以下のJSONメッセージを貼り付けます。

     {
     "code": "HELLO_WORLD",
     "compatible": true,
     "created": "2018-04-17T12:04:36.115+0000",
     "createdBy": "ICSAdmin",
     "description": "Example describing simple log and notification actions.",
     "endPointURI": "https://<host>:<port>/flows/rest/HELLO_WORLD/1.0/metadata"
     }
    
  8. ダイアログ画面で次 >をクリックすると、以下のようなサマリー画面に到達しますので、完了をクリックします。

    image24

  9. 呼び出し側も同様に、先ほど作成したREST接続を呼出しのドラッグ・アンド・ドロップへドラッグします。

    image25

  10. 基本情報の設定画面で例えば次のように入力し次 >をクリックします。本演習では指示がないフィールドはデフォルトのままとしてください。

    フィールド 入力値
    エンドポイントにどのような名前を付けますか。 RetrieveMetadata
    このエンドポイントで何が行われますか。 入力不要
    エンドポイントの相対リソースURLは何ですか。 /ic/api/integration/v1/integrations/{id}
    エンドポイントでえどのアクションを実行しますか。 GET
    このエンドポイントのパラメータを追加して確認 入力不要(チェック)
    このエンドポイントを構成してレスポンスを受信 チェック
  11. リクエスト・パラメータの設定画面ではそのまま次 >をクリックします。

  12. レスポンス・ペイロードの設定画面ではレスポンス・ペイロード・ファイルとしてJSONサンプルを選択し、ファイルを選択をクリックして、JSONレスポンス・ペイロードの取得の項で保存したJSONファイルを選択します。取り込みが完了したら次 >をクリックします。

  13. サマリーの画面で完了をクリックします。


データ・マッピングとアクティブ化

REST-ProxyからRetrieveMetadataにリクエストデータを受け渡すときのデータ・マッピングと、RetrieveMetadataからREST-Proxyにレスポンスデータを受け渡すときのデータ・マッピングを、それぞれ定義します。

  1. リクエスト・マッピングのアイコンをクリックし、アイコンを押してデータ・マッパーを起動します。

    image26

  2. 次のソース・フィールドを対応するターゲット・フィールドへマッピングします。ソース・フィールドをドラッグして、ターゲット・フィールドのテキストと重なるように調整します。

    ソース・フィールド ターゲット・フィールド
    execute > QueryParameters > id execute > TemplateParameters > id

    image27

  3. 検証を押し、問題ないことを確認後、閉じるをクリックします。

    image28

  4. レスポンス・マッピングのアイコンをクリックし、アイコンを押してデータ・マッパーを起動します。

    image29

  5. 次のソース・フィールドを対応するターゲット・フィールドへマッピングします。

    ソース・フィールド ターゲット・フィールド
    executeResponse > response-wrapper > code executeResponse > response-wrapper > code
    executeResponse > response-wrapper > compatible executeResponse > response-wrapper > compatible
    executeResponse > response-wrapper > created executeResponse > response-wrapper > created
    executeResponse > response-wrapper > createdBy executeResponse > response-wrapper > createdBy
    executeResponse > response-wrapper > description executeResponse > response-wrapper > description
    executeResponse > response-wrapper > endPointURI executeResponse > response-wrapper > endPointURI
  6. マッピングが完了すると、画面が次のようになります。

    image30

  7. 検証をクリックし、問題ないことを確認後、閉じるをクリックします。

  8. 最後にメッセージ・トラッキングの設定をします。画面右上のメニューを開き、トラッキングをクリックします。

    image31

  9. ソースのフィールド一覧からidをドラッグし、トラッキング・フィールドへドロップします。そして保存をクリックします。

    image32

  10. これで統合の設定が完了です。右上のインジケータが100%になっていることを確認し、保存閉じるをクリックします。

  11. 統合の設定が100%完了すると、統合をアクティブにするためのトグル・ボタンが表示されます。トグル・ボタンをクリックし、統合をアクティブ化します。

    image33

  12. 確認のダイアログでは何も設定せず、そのまま、アクティブ化をクリックします。アクティベーションのプロセスが完了するのを待ちます。


統合のテストとモニタリング

  1. 歯車のアイコンをクリックしてエンドポイントURLのリンクをクリックします。

    image34

  2. 新しいタブが開きます(認証を求められる場合はOICへのログイン情報を入力します)。このページでは、リソース・エンドポイントやメソッド、必要なパラメータ情報などを確認してください。

    • リソース・エンドポイントやメソッド、必要なパラメータ情報
    • トリガー側への設定が、このREST APIの起動方法に反映されていること
    • レスポンス・ペイロードとしてアップロードしたJSONファイルが、サンプル・ペイロードとして使われていること
  3. Swaggerのリンクをクリックすると、メタデータをOpenAPI 2.0(Swagger)形式で取得できます。

    image35

  4. OpenAPI 2.0 (Swagger)形式

    image36

  5. エンドポイントを、RESTメッセージの送信できるアプリケーションでテストします。

Advanced REST clientを使った手順:

  1. エンドポイントのURLをコピーし、Request URLに貼り付けします。このとき、以下のようにパラメータの記載を変更してください。

    image37

    変更前 変更後
    [id] ${id}
  2. VariablesタブのADD VARIABLEをクリックします。

    image38

  3. リクエスト・パラメータを次の通り設定します。

    Name Value
    id GET_INTEGRAT_METADATA_<USER NAME>|01.00.0000
    * tips: 自分で作成した統合のメタデータを取得します
  4. SENDをクリックして作成したREST APIを呼び出します。JSON形式で期待するレスポンスを受け取っていることを確認してください。

    image39

  5. モニタリング画面から統合の成功を確認します。OICのホーム画面に移動し、下方にスクロールすると、OIC全体のモニタリング結果を確認できます。

    image40

  6. Monitoringボタンをクリックして、詳細を確認します。

    image41

  7. 先ほどテストで実行したメッセージの結果を確認するには、メニューでトラッキングをクリックします。

    image42

  8. 統合が正常に完了していることを確認します。このとき、メッセージ・トラッキングとして設定したフィールド(id)の値が表示されていることを確認します。

    image44

  9. トラッキング・ペイロードのリンクをクリックすると、連携の実行結果を確認できます。エラーが発生した場合には発生個所の特定に利用できます。

    成功した場合

    image46

    失敗した場合

    image47


以上でIntegrationのチュートリアルは終了です。