Oracle Cloud Oracle Integration 3のRapid Adapter Builderの開始

Oracle Integration 3のRapid Adapter Builderの開始

このクイック・スタート・ガイドでは、Rapid Adapter Builderの基本をOracle Integrationで学習し、アプリケーションのサンプル・アダプタを構築します。

Oracle Integrationを初めて使用する場合は、このチュートリアルを開始する前に、その主要な概念(統合、接続、マッピングなど)をよく理解してください。「Oracle Integration 3での統合の使用」の「統合の概念」と「接続について」を参照してください。

ノート:

このチュートリアルでは、Oracle Cloudにアクセスする必要があります。無料アカウントにサインアップするには、「Oracle Cloud Infrastructure Free Tierを使い始める」を参照してください。

Rapid Adapter Builderについて

Oracle IntegrationのRapid Adapter Builderを使用すると、複雑なコードを最初から開発しなくても、RESTful APIを公開するアプリケーション用のアダプタを構築できます。

Oracle Integrationでは、アダプタは、統合フローを特定のアプリケーションに接続するためのインタフェースを提供します。アダプタは、接続メソッドに関連する複雑さを排除することで、統合を簡素化します。アダプタを使用して、接続の作成、呼出しエンドポイントとトリガー・エンドポイントの構成、および統合の設計時のランタイム・アクティビティのサポートを行うことができます。

Oracle Integrationには、統合シナリオにすぐに使用できるアプリケーション固有のアダプタの増え続けるライブラリがあります。ただし、Oracle提供のアダプタが使用できない場合は、Rapid Adapter Builderを使用して独自のアダプタを構築できます。 Oracle Integrationのアダプタを構築するために必要なすべてのインフラストラクチャを提供します。 Rapid Adapter Builderを使用して構築されたアダプタは、Oracle提供のアダプタと同じ機能を提供できます。 Oracle Integrationの既存のアダプタで使用可能な動作と同様の動作を実装できます。

Rapid Adapter Builderは、Visual Studio Code (VS Code)拡張機能として使用でき、アダプタの構築に必要なコードを生成するのに役立ちます。この拡張機能を使用すると、アダプタを反復的に開発し、それをOracle Integrationに公開できます。

アダプタ定義ドキュメントについて

アダプタをOracle Integrationに公開するには、アダプタ定義ドキュメントと呼ばれるJSONメタデータ・ファイルでアダプタの仕様と関数を定義する必要があります。

アダプタ定義ドキュメントでは、通常、アダプタの設計と実装について説明します。アダプタの動作とプロパティに関する情報が含まれています。 Rapid Adapter Builderを使用すると、アプリケーションのAPIのPostmanコレクション(または一連のアプリケーションAPIを記述するOpenAPIドキュメント)からアダプタ定義ドキュメントをすばやく作成し、要件に応じてアダプタ定義ドキュメントを手動で変更できます。

アダプタ定義ドキュメントは、次のセクションで構成されています:

セクション	説明
`info`	アダプタの一般情報とブランディングについて説明します。
`schemas`	Oracle Integrationのマッパーに表示される構造を定義します。
`connection`	アダプタでサポートされている接続パラメータおよびセキュリティ・ポリシーを定義します。
`triggers`	アダプタが統合を開始するために受信できるイベントを定義します。
`actions`	ターゲット・アプリケーションに対して実装できる操作を定義します。アクションは、ターゲット・アプリケーションで使用可能な操作および公開される操作のユーザー中心のカプセル化を提供します。
`categories`	より優れたユーザー・エクスペリエンスを実現するためのアクションとトリガーのグループ化を定義します。
`flows`	アダプタを実行する実装ロジックを定義します。フローは、Cloud Native Computing Foundation (CNCF)プロジェクトのサーバーレス・ワークフロー仕様でサポートされている構成のサブセットを使用してモデル化されます。

サンプル・アダプタの作成

この項では、Rapid Adapter Builderを使用してサンプル・アダプタを迅速に構築する方法を学習します。

このチュートリアルでは、OpenWeatherアプリケーション用のアダプタを構築します。アダプタは、OpenWeatherによって提供されるパブリックAPIを使用して、特定の都市の天気情報を取得します。このアダプタを構築したら、Oracle Integrationに登録します。

ノート:

このチュートリアルでは、アプリケーションのAPIのPostmanコレクションを使用したアダプタの構築について説明します。ただし、OpenAPIドキュメント(一連のアプリケーションAPIの説明)を使用してアダプタを構築することもできます。詳細は、「Oracle Integration 3でのRapid Adapter Builderの使用」の「アダプタの構築およびテストのワークフロー」を参照してください。

次のタスクを実行して、最初のアダプタを構築します:

前提条件の完了
OpenWeatherのAPIリクエストの作成
APIリクエストを使用したPostmanコレクションの作成
アダプタ定義ドキュメントの生成
アダプタ定義ドキュメントの検証
Oracle Integrationへのアダプタの登録

前提条件の完了

アダプタの構築を開始する前に、Oracle Integrationへのアクセスの取得、必要なソフトウェアのインストールなど、いくつかの前提条件タスクを完了する必要があります。

順序	タスク	詳細情報
1	Oracle Integrationへのアクセス	まだ持っていない場合は、次を取得します: Oracle Integrationのアカウント(サインイン資格証明を含む) Oracle IntegrationインスタンスのURL Oracle Integration管理者と協力して、このタスクを完了します。
2	Oracle IntegrationインスタンスのOracle Cloud Infrastructure Identity and Access Management (IAM)にクライアント・アプリケーションを作成し、クライアント資格証明を取得	「クライアント・アプリケーションの作成および資格証明の取得」を参照してください。
3	前に作成したクライアント・アプリケーションに統合インスタンス開発者ロールを割り当てます	「クライアント・アプリケーションへの統合インスタンス開発者ロールの割当て」を参照してください。
4	必要なソフトウェアをダウンロードしてインストールします	「必要なソフトウェアのダウンロードとインストール」を参照してください。
5	Rapid Adapter Builder用のVS Code拡張機能のインストール	「Rapid Adapter Builder用のVS Code拡張機能のインストール」を参照してください。
6	Rapid Adapter BuilderのVS Code拡張機能の構成	「Rapid Adapter BuilderのVS Code拡張機能の構成」を参照してください。

クライアント・アプリケーションの作成および資格証明の取得

Oracle Cloud Infrastructure Identity and Access Management (IAM)で、Oracle Integrationインスタンスのクライアント・アプリケーションを作成し、クライアント資格証明を取得します。

これらのクライアント資格証明は、Rapid Adapter Builderを使用してアダプタを公開する際に、パブリッシャ・プロファイルの詳細で使用します。

クライアント・アプリケーションを作成し、必要な詳細を取得するには、「Oracle Identity Domain環境でのOAuth 2.0付与の使用」の「クライアント資格証明およびリソース所有者のパスワード資格証明の前提条件」を参照してください。「クライアント資格証明」権限タイプを選択します。

Oracle Integrationインスタンスに関する次の詳細を取得する必要があります:

Host: Oracle IntegrationインスタンスのURL
integrationInstance: Oracle Integrationインスタンスの名前
次のクライアント資格証明:
- tokenUrl
- clientId
- clientSecret
- scope

クライアント・アプリケーションへの統合インスタンス開発者ロールの割当て

クライアント資格証明を正常に使用するには、以前に作成したクライアント・アプリケーションに統合インスタンス開発者ロールを割り当てます。

必要なロールをクライアント・アプリケーションに割り当てるには:

Oracle Cloudコンソールにログインします。
ナビゲーション・ペインで、Oracle Cloud Servicesをクリックします。

Oracle Cloud Servicesページが表示されます。
Oracle Integrationインスタンスに対応する特定のアプリケーションを選択します。
ナビゲーション・ペインで、「アプリケーション・ロール」をクリックします。

適用可能なすべてのロールのリストが表示されます。
ServiceDeveloperロールを展開し、「割当済アプリケーション」の横にある「管理」をクリックします。
「使用可能なアプリケーションの表示」をクリックします。
作成したアプリケーションを選択し、「割当」をクリックし、「閉じる」をクリックします。
これで、IAMによって統合インスタンス開発者ロールがアプリケーションに割り当てられます。

必要なソフトウェアのダウンロードとインストール

Rapid Adapter Builderを使用するには、追加のアプリケーションまたはソフトウェアがシステムにインストールされている必要があります。

Postmanアプリケーションをダウンロードしてインストールします。「Postmanのダウンロード」ページにアクセスします。 Postmanでアカウントを作成し、すべての機能にアクセスします。
VS Codeをダウンロードしてインストールします。「Visual Studio Codeのダウンロード」ページにアクセスします。

VS Codeバージョン1.73.0以上を使用する必要があります。

Rapid Adapter Builder用のVS Code拡張機能のインストール

Rapid Adapter BuilderのVS Code拡張機能をダウンロードしてインストールします。

Visual Studio Marketplaceで、Oracleのページにアクセスしてください。
「Oracle Integration CloudRapid Adapter Builder」タイルを見つけてクリックします。
「詳細」ページが開きます。
「インストール」をクリックします。
拡張ファイルがVS Codeで開きます。
VS Codeの「インストール」をクリックします。
これで、拡張機能がインストールされ、サイドバーに表示されます。

Rapid Adapter BuilderのVS Code拡張機能の構成

Rapid Adapter BuilderのVS Code拡張機能をインストールした後、システム上のワークスペースを初期化し、その拡張のパブリッシャ・プロファイルを構成する必要があります。

構造化ワークスペースとして使用するシステム上のフォルダを選択し、その中のアダプタ関連のアーティファクトを整理します。 VS Code拡張機能を使用して、このワークスペースを初期化します。

また、アダプタを公開するOracle Integrationインスタンスの詳細を使用して、拡張のパブリッシャ・プロファイルを更新します。以前に取得したクライアント資格証明と、いくつかの追加データを入力します。パブリッシャ・プロファイルの情報は、様々なタスクについて、指定されたOracle Integrationインスタンスと通信するために使用されます。拡張機能では、Oracle Integrationインスタンスごとに入力したクライアント資格証明がpublisher-profiles.yamlファイルに安全に格納されます。 yamlファイルの構造は次のとおりです:

プロパティ名	定義
`active`	使用するアクティブなプロファイル。値は、プロファイル・リストのプロファイル名と一致する必要があります。
`profiles`	プロファイル・オブジェクトの配列。
`profiles[*].name`	プロファイルの一意の名前。
`profiles[*].host`	REST APIのOracle Integrationインスタンスの設計時URL。
`profiles[*].integrationInstance`	Oracle Integrationインスタンスの名前。
`profiles[*].auth.tokenUrl`	Oracle Integrationインスタンスのget-token URL。Oracle Cloud Infrastructure Identity and Access Management (IAM)から取得されます。
`profiles[*].auth.clientId`	IAMの構成済アプリケーションのクライアントID。
`profiles[*].auth.clientSecret`	IAMの構成済アプリケーションのクライアント・シークレット。
`profiles[*].auth.scope`	IAMで構成されたアプリケーションの許可されたスコープ。

VS Codeで次のタスクを実行して、必要な構成を行います。

VS Code拡張を使用してワークスペースを初期化します。
1. VS Codeで、サイドバーの「エクスプローラ」をクリックします。
2. 「フォルダを開く」をクリックし、アダプタ開発のワークスペースとしてシステム上のフォルダを選択します。
  これで、エクスプローラ・ビューの左側にフォルダがリストされます。
  
  ノート:
  上部のリボンの「ファイル」をクリックし、「フォルダを開く...」を選択してVS Codeのフォルダを開くこともできます。
3. Ctrl + Shift + Pを押してコマンド・パレットを開き、RAB: Initialize Workspaceと入力して、Enterを押します。
  VS Code拡張は、ワークスペースを初期化し、ワークスペース内にいくつかのディレクトリおよびテンプレート・ファイルを作成します。作成されたディレクトリおよびファイルは、左側のエクスプローラ・ビューに表示されます。次のディレクトリおよびファイルが作成されます:
  - api: このフォルダには、すべてのOpenAPIファイルを保存できます。
    
    ノート:
    OpenAPIドキュメントをアダプタ・バンドルにパッケージ化するVS Code拡張機能の場合、OpenAPIドキュメントの名前をopenapi.resource.jsonに変更します。
  - definitions: 拡張機能により、このフォルダにデフォルトのアダプタ定義ドキュメントmain.add.jsonが作成されます。デフォルトのドキュメントは、PostmanコレクションまたはOpenAPIファイルのデータで上書きできます。さらに、生成したその他のアダプタ定義ドキュメントはすべて、このフォルダに保存されます。すべてのアダプタ定義ドキュメントのファイル名には、.add.jsonが付加されます。
  - misc: すべてのPostmanコレクションをこのフォルダに保存できます。すべてのPostmanコレクションのファイル名に.postman_collection.jsonが付加されていることを確認します。
  - logo.svg: アダプタのデフォルトのロゴ・ファイルがルート・フォルダの下に作成されます。このファイルを必要なイメージに置き換えることができます。
拡張機能のパブリッシャ・プロファイルを構成します。
1. VS Codeで、サイドバーの「OIC Rapid Adapter Builder」をクリックします。
2. 結果のビューで、「パブリッシャ・プロファイル」セクションの「編集」をクリックします。
  publisher-profiles.yamlファイルがエディタで開きます。
3. 前に取得したクライアント資格証明でファイルを更新します。「クライアント・アプリケーションの作成および資格証明の取得」を参照してください。また、使用するプロファイルの名前でactiveフィールドを更新します。
4. キーボードのCtrl+Sを押してファイルを保存します。
複数のOracle Integrationインスタンスの資格証明を入力すると、.yamlファイルは、詳細をインデントして実装された階層構造に格納されます。

次の例は、.yamlファイルに格納されている2つのOracle Integrationインスタンス(Test_Lab1およびTest_Lab2)の詳細を示しています。
```
# select which profile to use.
active: Test_Lab1

# multiple profiles can be defined.
profiles:  
  - name: Test_Lab1
    host: https://<oicinstance.oraclecloud.com>
    integrationInstance: example-instance1
    auth:
      tokenUrl: https://<IAM-token>/oauth2/v1/token
      clientId: ef8xxxxxbf0c4101a4f74ae5fe301exx
      clientSecret: 0ebdae12-xxxx-4182-9051-8dbd83b2xxxx
      scope: https://08DADxxxx9D4496F9FBAFxxCFA1B0657.integration.region-1.oraclecloud.com:443urn:opc:resource:consumer::all
  - name: Test_Lab2
    host: https://<oicinstance.oraclecloud.com>
    integrationInstance: example-instance2
    auth:
      tokenUrl: https://<IAM-token>/oauth2/v1/token
      clientId: ef9xxxxxbf0c4101a4f74ae5fe301exx
      clientSecret: 1ebdae12-xxxx-4182-9051-8dbd83b2xxxx
      scope: https://18DADxxxx9D4496F9FBAFxxCFA1B0657.integration.region-2.oraclecloud.com:443urn:opc:resource:consumer::all        
```

OpenWeatherのAPIリクエストの作成

アプリケーションに対してAPIリクエストを行うには、アプリケーションで使用可能なAPIドキュメントを使用してリクエスト形式を識別する必要があります。

OpenWeatherアプリケーションの場合、天気リクエストAPIの形式は次のとおりです:

https://api.openweathermap.org/data/2.5/weather?q={City Name}&appid={API Key}

リクエストの一部として、ロケーションの名前と、OpenWeatherアプリケーションで作成されたAPIキーを指定する必要があります。

OpenWeather APIキーを取得し、リクエストを作成します。

APIキーを取得するには、OpenWeatherにアカウントを作成します。「OpenWeatherサインアップ」ページにアクセスします。
Eメール・アドレスを確認し、サインアップ・プロセスを完了すると、登録済Eメール・アドレスにAPIキーが届きます。 APIキーは、登録後数時間後にアクティブ化されることに注意してください。
特定のロケーションのAPIリクエストを構築します。次に、APIキーの例を使用したロンドンの都市のAPIコールの例を示します:
api.openweathermap.org/data/2.5/weather?q=London&APPID=09d2d589238d5f0d858f6ea46f5d71bf

APIリクエストを使用したPostmanコレクションの作成

Postmanアプリケーションでコレクションを作成し、作成したAPIリクエストを追加してテストし、コレクションをJSONファイルにエクスポートします。

Postmanアプリケーションを開き、アカウントでサインインします。
コレクションの作成
1. 左ペインで「コレクション」が選択されている状態で、「新規」をクリックし、表示されるダイアログで「コレクション」をクリックします。
  新しい空白のコレクションが作成され、左ペインにリストされます。
2. 右側の「概要」タブで、デフォルトのコレクション名(「新規コレクション」)をクリックしてコレクションの名前を変更します。新しい名前としてGet Weather Data Collectionと入力します。
前に作成したAPIリクエストをコレクションに追加し、テストして、レスポンスを例として保存します。
1. 左ペインで、新しく作成されたコレクションの下にある「リクエストの追加」をクリックします。
  新しい空白のリクエストが作成され、表示されます。
2. リクエストのURLフィールドで、GETコマンドを選択して、前に構築したAPIリクエストを入力します。問合せパラメータqおよびappidは、APIリクエストのデータに従って表に自動的に移入されることに注意してください。
3. リクエストをテストするには、「送信」をクリックします。
  「レスポンス」セクションには、受信した天気データが表示されます。レスポンスの例を次に示します:
```
{
    "coord": {
        "lon": -0.1257,
        "lat": 51.5085
    },
    "weather": [
        {
            "id": 803,
            "main": "Clouds",
            "description": "broken clouds",
            "icon": "04d"
        }
    ],
    "base": "stations",
    "main": {
        "temp": 279.09,
        "feels_like": 276.39,
        "temp_min": 277.86,
        "temp_max": 280.26,
        "pressure": 1015,
        "humidity": 86
    },
    "visibility": 10000,
    "wind": {
        "speed": 3.6,
        "deg": 350
    },
    "clouds": {
        "all": 75
    },
    "dt": 1704540946,
    "sys": {
        "type": 2,
        "id": 2075535,
        "country": "GB",
        "sunrise": 1704528308,
        "sunset": 1704557195
    },
    "timezone": 0,
    "id": 2643743,
    "name": "London",
    "cod": 200
}
```
4. 「レスポンス」セクションで、「例として保存」をクリックしてレスポンスを保存します。
  
  新しい例が作成され、表示されます。
  
  Rapid Adapter Builderでアダプタ定義ドキュメントにスキーマを生成するには、リクエストに対して受信したレスポンスを保存する必要があります。
5. 左側のペインで、リクエスト・アイテムをクリックして「例」ページから「リクエスト」ページに戻り、「保存」をクリックしてリクエスト全体を保存します。
Postmanコレクションをワークスペースにエクスポートします。
1. 左側のペインで、「気象データ収集の取得」をポイントし、「他のアクションを表示」をクリックしてから、表示されるメニューから「エクスポート」をクリックします。
2. 「コレクションをエクスポート」ダイアログで、デフォルト・オプションを選択したままにして、「エクスポート」をクリックします。
3. 「ファイルを保存するパスの選択」ウィンドウで、前にワークスペースとして選択および初期化したフォルダに移動します。「Rapid Adapter BuilderのVS Code拡張機能の構成」を参照してください。ワークスペース・フォルダで、「その他」ディレクトリを開き、「保存」をクリックしてファイルをこのディレクトリにエクスポートします。
  
  Postmanコレクションは、Get Weather Data Collection.postman_collection.jsonという名前のJSONファイルとして保存されます。
  
  ノート:
  Rapid Adapter Builderでコレクションをアダプタ定義ドキュメントに変換するには、Postmanコレクションのファイル名に常にサフィクス.postman_collectionが含まれている必要があります。

アダプタ定義ドキュメントの生成

Rapid Adapter BuilderのVS Code拡張機能を使用すると、エクスポートされたPostmanコレクションからアダプタ定義ドキュメントを生成できます。

VS Codeで、サイドバーの「エクスプローラ」をクリックしてエクスプローラ・ビューを表示します。
ワークスペース・フォルダのディレクトリ構造が表示されます。
「その他」ディレクトリ・リストをクリックして展開します。
エクスポートされたコレクション・ファイル(Get Weather Data Collection.postman_collection.json)を右クリックし、「RAB: Postmanコレクションを変換」をクリックします。
「リクエストの選択」ペインで、変換するリクエストを選択し、「完了」をクリックします。
表示されるダイアログ・ボックスで、「メインの更新」をクリックします。
これで、VS Code拡張は、Postmanコレクションのデータを変換し、ワークスペースのdefinitionsディレクトリ内のデフォルトのアダプタ定義ドキュメント(main.add.json)に追加します。さらに、ドキュメントがVS Codeエディタで開きます。
エディタで、次のようにドキュメントのinfoセクションを更新します:
```
"id": "oracledemo:getweather",
    "displayName": "Get Weather Data",
    "description": "Get Weather Data Connector",
```
アダプタをOracle Integrationに公開すると、ここで指定した表示名がアダプタの名前として表示されます。
アダプタ定義ドキュメントにAPIレスポンス・スキーマが含まれていることを確認してください。
キーボードのCtrl+Sを押してファイルを保存します。

アダプタ定義ドキュメントの検証

アダプタをOracle Integrationに公開する前に、アダプタ定義ドキュメントを検証する必要があります。ドキュメントを検証することで、構文エラーやセマンティック・エラーが含まれていないことを確認します。

VS Codeで、サイドバーの「エクスプローラ」をクリックします。
ワークスペース・フォルダのディレクトリ構造が表示されます。
「定義」ディレクトリ・リストをクリックして展開します。
アダプタ定義ドキュメント(main.add.json)を右クリックし、「RAB: 検証」をクリックします。
これで、VS Code拡張によってドキュメントが検証されます。ドキュメントが有効な場合は、VS Codeエディタの下部パネルの「出力」タブに、成功メッセージが表示されます。

Oracle Integrationへのアダプタの登録

アダプタ定義ドキュメントを検証した後、Oracle Integrationでアダプタを使用可能にできます。

Ctrl + Shift + Pを押して、コマンド・パレットを開きます。表示されるコマンドで、RAB: Register RAB Bundleコマンドをクリックします。

これで、VS Code拡張は、アダプタをOracle Integrationインスタンスに登録します。アダプタは、パブリッシャ・プロファイルで「アクティブ」として指定されたインスタンスに登録されます。

登録が完了すると、成功メッセージがVS Codeエディタの下部パネルの「出力」タブに表示されます。
Oracle Integrationインスタンスにログインし、登録されているアダプタを確認します。
1. Oracle Integrationホームページで、「ナビゲーション・メニューの表示/非表示」をクリックしてナビゲーション・ペインを表示します。
2. ナビゲーション・ペインで、「設計」をクリックし、「アダプタ」をクリックします。
3. 「アダプタ」ページで、「検索」アイコンをクリックし、アダプタの名前を「検索」フィールドに入力して、Enterを押します。
公開したアダプタが検索結果に表示されます。アダプタの行をポイントし、「ビュー」をクリックしてその詳細を表示します。

おめでとうございます! これで、Rapid Adapter Builderを使用して最初のアダプタが正常に構築および公開されました。

ドキュメントのアクセシビリティについて

オラクルのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。

Oracle Supportへのアクセス

サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。

タイトルおよび著作権情報

Oracle Cloud Oracle Integration 3のRapid Adapter Builderの開始

F85991-08

Oracle and/or its affiliates.

原本主著者: Oracle Corporation