アダプタを作成するためのベスト・プラクティス

一般的なガイドライン

アダプタの動作が、統合フローやプロジェクトなどのライフ・サイクルにおけるアダプタの参加に関してOracle提供のアダプタによって示される全体的な動作と同一であることを確認します。
アダプタを反復的に開発します。この開発および配信のメカニズムは、Rapid Adapter Builderインフラストラクチャで強くサポートされています。
このアプローチには多くの利点があります。たとえば、時間をより適切に追跡し、より頻繁なリリース(必要な場合)を提供し、変化する要件に迅速に対応し、分離してテストできます。また、1ダース以上のAPIを一度に確認してテストする必要もありません。
Oracleでは、小規模な開始と反復の開始に加えて、必要に応じてテストすることをお薦めします。たとえば、単一のAPIの要件を指定した後、次のAPIを追加する前にアダプタをテストします。
テストのレベルはあなた次第です。機能テストのみに集中し、リリースに必要なすべての機能をアダプタに追加した後、他のすべてのテストを保存できます。または、より広範なテストを選択することもできます。
アダプタを開発する際は、ビジネス・プロセスを念頭に置いてください。アダプタは、Oracle Integrationの特定のビジネス・プロセスの実装に必要なすべての機能を公開する必要があります。たとえば:
- Oracle Integrationをコールしてダウンストリーム・アプリケーションにリアルタイム更新を送信する場合、アダプタはダウンストリーム・アプリケーションAPIをコールするためのサポートを確実に公開する必要があります。
- ソース・アプリケーションで実行されている作成、更新または削除操作を様々なシステムにリレーするビジネス・プロセスの場合、ソース・アプリケーションのアダプタは、ソース・アプリケーションの様々なリソースに変更が発生したときに統合フローを起動する機能(Oracle Integration内)を持つトリガーをサポートする必要があります。
変更や拡張機能にバージョニングを使用します。 Rapid Adapter Builderでは、特定のメジャー・バージョンに対して複数のマイナー・バージョンを配信できます。現時点では、Rapid Adapter Builderは1つのアダプタに対して1つのメジャー・バージョンのみをサポートします。「セマンティック・バージョン・チェックのルール」を参照してください。
特定のメジャー・バージョンのアダプタの最新マイナー・バージョンが最新のOracle Integrationリリースに対して検証されていることを確認します。下位レベルの環境に最新のOracle Integration更新でパッチが適用される場合も同様です。
以前のバージョンのOracle Integrationに対して動作していたアダプタが新しいリリースに対して問題が発生し始めた場合、Oracle Integrationに対するファイル・サービス・リクエスト。
次のマイナー・バージョンを公開する前に、すべての適切なテストおよび検証が実行されていることを確認します。
前述のアプリケーション・バージョン、接続および統合フロー(ドラフトおよびデプロイ済)に対して構築された既存のアーティファクトは、顧客の介入を必要とせずに、アップグレードされたアプリケーション・バージョンに対してシームレスに作業を続行する必要があります。
次のアーティファクトでアダプタを使用できることを確認します:
- すべての統合パターン
- グローバルまたはプロジェクト固有のアダプタ接続
- 共有アダプタ接続
- アクセラレータまたはレシピ
統合開発者がアダプタを操作するのに役立つドキュメントを作成します。
使用するアダプタのドキュメント・テンプレートおよびアダプタの命名ガイドラインについては、Oracleにお問い合せください。

接続のガイドライン

一般的な接続ガイドライン

次の項目に制限を課さないでください:
- フロー内およびフロー間の単一接続のエンドポイント構成の数。
- 同じ構成を持つエンドポイント構成の数。

テスト接続ガイドライン

テスト接続によって、作成済ペイロードを持つライブ・エンドポイントに対してべき等な(非破壊的な)操作(HTTP GET)が起動され、サービスが消費可能(アウトバウンド・プロキシ、TLSバージョン、SSLハンドシェイク、認証および認可関連のエラー、およびレンダリングに必要な規範的な推奨事項)になるようにしてください。「フローを使用したテスト接続動作の実装」を参照してください。
アダプタがサポートされていないアプリケーション・バージョンへのアウトバウンド接続を作成しようとしたときに、テスト接続が失敗し、適切なメッセージがスローされることを確認します。
サポートされている最小および最大リリースをエラー・メッセージに表示します。
「接続」ページに、完了する必要があるアプリケーションの前提条件が表示されていることを確認します。

接続変更のガイドライン

アダプタを利用する既存のデプロイ済Oracle Integrationフローが、接続に対する次の変更後に非アクティブ化/再アクティブ化を行わずに引き続き機能することを確認します:
- パスワード/APIキー
- セキュリティ・ポリシー (例: HTTP Basic認証からユーザー名トークン; HTTP Basic認証からOAuthリソース所有者パスワード・フロー)
- OAuthフローの場合の委任認可に対する新しい同意(スコープの変更がないと仮定)
- エンドポイントURL (新しいインスタンスが既存のインスタンスのものと同一の場合 - たとえば、アプリケーションPODが1ゾーンから別のゾーンに移動したとします)
- ユーザー名(新しいユーザーが前のユーザーと同じ権限およびロールを持っていると仮定)
- 追加の接続メタデータのコレクション。

アダプタのデザインタイム、ランタイムおよびライフ・サイクル管理のガイドライン

通常、アダプタは、アプリケーションで導入された新しいパブリックに消費可能なビジネスobjects/APIs/eventsを自動的に検出する必要があります
- アダプタ・コンシューマが次回のアダプタ・リリースでこれらのオブジェクトを消費するまで待機するアダプタにコードの変更は発生しません。
- ビジネス・オブジェクト/APIの可用性後に作成されたOracle Integrationフローで、これらのオブジェクトを検出できることを確認します。
特定のビジネス・ドメインをターゲットとするアダプタを開発できます。ビジネス・オブジェクトおよび操作の選択に固有のアクションを表示するようにコーディングできます。

データ・ソース・カスタマイズのガイドライン

カスタム・オブジェクトおよび属性が自動的に検出可能であることを確認します。
カスタム・オブジェクトおよびカスタム属性に、Oracle Integrationの機能名(フィールド1、フィールド2などではなく)が表示されていることを確認します。
アプリケーションがデータ・モデルへのカスタマイズをサポートしているアダプタに対して「再生成」オプションが使用可能であることを確認します。
既存のアダプタ構成ウィザードの再編集によって、新しいカスタム・オブジェクトおよびカスタム属性が自動的に挿入されるようにします。

統合フロー・プロモーションまたはアプリケーション・アップグレードのガイドライン

アクティブ化時に上位のOracle Integration環境にインポートすると、(新しく作成されたアダプタの)統合フロー・アーカイブ(IAR)ファイルがターゲット・アプリケーション・インスタンスに対して機能することを確認します。
- アダプタ・コンシューマが、上位のOracle Integration環境でアダプタ構成を再編集するよう求められていないことを確認します。
- アダプタ定義ドキュメントに格納されている外部アプリケーションまたはデータ・ソース固有のエンドポイントの詳細をハード・ワイヤリングしないでください。
アプリケーションのアップグレードが透明であることを確認します。既存のフローは、変更、本番停止およびパッチなしで、アップグレードされたアプリケーション・インスタンスに対して動作する必要があります。
アダプタ・コンシューマが、新しいアプリケーション・リリースまたは新しいバージョンの外部データ・ソースに対して動作する新しい接続の作成を強制されないようにします。
アダプタ・コンシューマが(アダプタを参照する)既存のフローを非アクティブ化して再アクティブ化し、外部アプリケーションの新しいリリースに対して機能しないようにします。
オプションで、アダプタ・リリースの後続のマイナー・バージョンでは、アプリケーションに追加された新しいインフラストラクチャ機能(新しい認証/認可ポリシーのサポート、バルク・データ・インポートなど)を提供できます。
新しいフローが最新のアプリケーション・リリースに対して動作するようにし、動作の変更や損失は発生しません。
アダプタは、新しいバージョンのアプリケーション・リリースに対して認証する必要があります。
- 最新のアプリケーション・リリースでOracle Integrationフリートをリフレッシュする前に、必ず認証してください。
- 既存の自動化テストを実行して、回帰をテストします(ある場合)。
アダプタが、サポートされている既存のすべてのアプリケーション・バージョンに対して機能することを確認します。
アダプタが機能するために、アダプタ・コンシューマが最近提供したアプリケーション・リリースにアップグレードする必要がある状況を回避します。
ただし、アダプタには、古いアプリケーション・リリースに対する機能が制限されている場合があります。

セキュリティ・ガイドライン

認証または認可のガイドライン

アダプタ定義ドキュメントでアクションの起動用にモデル化された接続定義によって、外部アプリケーションでサポートされているすべての認証および認可スキームのサポートが試行されることを確認します。
最もセキュアな認証スキームまたは認可スキームを、脆弱な認証スキームよりも公開することを優先します。
前のバージョンのアダプタに実装されている認証スキームは削除できませんが、新しい認証スキームを追加することはできます。

トランスポート・レベルのセキュリティ・ガイドライン

外部エンドポイントがTLS v1.3またはv1.2を使用して保護されていることを確認します。
TLS v1.1および1.0保護エンドポイントのサポートは避けてください。
自己署名証明書またはあまり知られていないCA署名証明書を使用して保護されている外部APIをコールしないでください。 Oracle Integrationは、この要件を想定しているアダプタにフラグを付け、そのようなアダプタをサブスクライブしているコンシューマに警告します。
アダプタ開発ドキュメントが、アダプタによってアウトバウンド・リクエストを送信する必要があるドメインにアドバタイズされていることを確認します。この情報は、消費者に理解してもらうために提示されます。 Oracle Integrationは、この情報がないアダプタにフラグを付け、そのようなアダプタをサブスクライブしているコンシューマに警告します。
トランスポート・レベルのセキュリティなしで、リクエストを平文で送信します。デフォルトでは、非SSLサポートは無効になっています。非暗号化モード(TLSなし)でワイヤー上でのデータの伝送をサポートすることを選択できますが、クレジット・スコア全体に悪影響を及ぼし、Oracle Integrationはこれらのアダプタをサブスクライブしているコンシューマに警告します。

バージョニング・ガイドライン

一般的なバージョニング・ガイドライン

アダプタを反復的に開発します。この開発および配信のメカニズムは、Rapid Adapter Builderインフラストラクチャで強くサポートされています。
変更や拡張機能にバージョニングを使用します。 Rapid Adapter Builderでは、特定のメジャー・バージョンに対して複数のマイナー・バージョンを配信できます。現時点では、Rapid Adapter Builderは1つのアダプタに対して1つのメジャー・バージョンのみをサポートします。「セマンティック・バージョン・チェックのルール」を参照してください。
マイナー・バージョンに下位互換性があり、コンシューマによるそのアダプタの最新および最大のマイナー・バージョンの取込み後も、以前のマイナー・バージョンのアダプタを使用して構築およびデプロイされた統合フローが、手作業による介入や中断なく引き続き機能することを確認します。

接続バージョニングのガイドライン

新しいリリースでは、既存の接続プロパティを削除できないことに注意してください。
新しい接続プロパティを必須にすることはできません。
既存のプロパティの機能動作は変更しないでください。
古いアダプタ・リリースで作成された接続が、新しいバージョンの取込み後に統合フローを作成するために使用できることを確認します。
以前のバージョンのアダプタ上に構築された既存のデプロイ済フローが、新しいバージョンの取込み後も引き続き機能することを確認します。
バージョニングでは、アダプタ・コンシューマが既存のフローを非アクティブ化および再アクティブ化する必要がないことを確認します。
新しいアダプタ・ランタイムが、既存のメタデータで発生したエラーを正常に処理することを確認します。 (既存のバグやパフォーマンスの問題を修正するためにアダプタが変更された場合でも、これを確認してください。)
新しいアダプタ・リリースで導入した新機能がオプトインであることを確認します。
ドラフト・モードの既存のフロー(機能的に完了)が、新しいバージョンのアダプタの取込み後にデプロイ可能であることを確認します。これによって、アダプタ・コンシューマは、すでに構成済の接続を構成したり、既存のアダプタ構成を再編集する必要がなくなります。

Oracle Integrationメッセージのガイドライン

新しいマイナー・バージョンのアダプタを使用して生成されたデータ構造に下位互換性があることを確認します。既存のエンドポイント構成を再構成する場合、前のバージョンのアダプタを使用して作成されたマップは失わないでください。
新しいマイナー・バージョンの取込み前に生成された既存のマップが、最新のマイナー・バージョンの取込み後に設計時と実行時の両方で引き続き機能することを確認します。

制限および制約のガイドライン

Rapid Adapter Builderには、いくつかの領域に制限があります。制限は、リソースの割当てまたは許容量です。アダプタに対して定義されているこれらの制限に従う必要があります。「制限」を参照してください。

ソース管理のガイドライン

作業バージョンを含むRapid Adapter Builderアーカイブがソース制御されていることを確認します。