第20章 OData への接続

OData (Open Data Protocol) は、REST API を構築および使用するための標準です。OData サービスは、OData 対応の HTTP リクエストを介して Fuse Online などのサービスをクライアントの提供します。Fuse Online インテグレーションは、OData サービスからエンティティーを取得でき、OData サービスによって管理されるエンティティーを更新、作成、または削除できます。これには、OData コネクションを作成し、そのコネクションをインテグレーションに追加します。

OData の仕様 を理解していることを前提とします。

OData サービスへの接続に関する詳細は、以下を参照してください。

20.1. OData サービスへのコネクションの作成

インテグレーションで、OData サービスによって管理されるエンティティーを取得、更新、作成、または削除するには、最初に OData サービスへのコネクションを作成する必要があります。

前提条件

  • 接続する OData サービスのベース URL を知っている必要があります。
  • サービスが認証を使用する場合はクレデンシャルが必要で、必要に応じて SSL 証明書が必要です。しかし、ほとんどの OData サービスはパブリックサービスであり、認証は必要ありません。

手順

  1. Fuse Online の左パネルで Connections をクリックし、利用可能なコネクションを表示します。
  2. Create Connection をクリックしてコネクターを表示します。
  3. OData コネクターをクリックします。
  4. コネクションを設定します。

    1. Service Root URL フィールドに、アクセスする OData サービスのベース URL を入力します。
    2. サービスが Basic 認証を使用する場合は、User Name フィールドにユーザー名を入力します。
    3. サービスが Basic 認証を使用する場合は、Password フィールドにパスワードを入力します。
    4. サービスが SSL 証明書を要求する場合は、Server Certificate フィールドに SSL 証明書の内容を貼り付けます。

      通常、パブリックの OData サービスには、ブラウザーによって提供される以外の証明書は必要ありません。しかし、内部 OData サービスでは、独自の SSL 署名書を作成し、自己署名した可能性があります。この証明書は認証局によって信用されないため、OData サービスへのコネクションに失敗します。コネクションを有効にするには、ここに自己署名証明書を貼り付けます。

      ブラウザーでサービスをロードするのが証明書を取得する 1 つの方法です。その後のステップは、使用しているブラウザーによって異なります。一般的に、アドレスバーの横にある Not secure 鍵マークをクリックして、View Certificate をクリックし、表示された証明書をファイルにエクスポートしてその証明書をコピーし、このフィールドに貼り付けるステップと似たものになります。

  5. Validate をクリックします。Fuse Online は即座にコネクションを検証しようとし、検証の成功または失敗を示すメッセージを表示します。検証に失敗した場合は、入力パラメーターを訂正し、再度検証を行います。
  6. 検証に成功したら Next をクリックします。
  7. Name フィールドに、このコネクションを別のコネクションと区別するために使用する名前を入力します。たとえば、OData North を入力します。
  8. Description は任意のフィールドで、このコネクションに関する便利な情報を入力します。
  9. Save をクリックし、作成したコネクションが利用可能になったことを確認します。上記の例の名前を入力した場合は、インテグレーションに追加できるコネクションとして OData North が表示されます。

次のステップ

OData コネクションをインテグレーションに追加します。

20.2. ポーリングが OData からデータを返すときにインテグレーションをトリガー

OData サービスからデータを取得したときにインテグレーションの実行をトリガーするには、OData コネクションを最初のコネクションとしてシンプルなインテグレーションに追加します。インテグレーションの実行時、OData コネクションは指定された間隔でサービスをポーリングします。コネクション設定を満たすデータが見つかると、コネクションはそのデータをインテグレーションの次のステップに渡します。

前提条件

OData コネクションが作成されている必要があります。

手順

  1. Fuse Online パネルの左側にある Integrations をクリックします。
  2. Create Integration をクリックします。
  3. Choose a connection ページで、インテグレーションを開始するために使用する OData コネクションをクリックします。
  4. Choose an action ページで Read アクションを選択します。
  5. Read アクションを設定します。

    1. Resource Collection フィールドで、クエリーを実行する OData リソースの名前を選択します。Fuse Online は OData サービスからデータを取得し、利用可能なリソースコレクションのリストを提供します。
    2. 特定の 1 つのエンティティーを取得するには、Entity Key Predicate フィールドにキー述語を指定してそのエンティティーを特定します。たとえば、UserName='Bob'Categories(1) を指定します。複数のエンティティーを取得する場合はこのフィールドを空白のままにしておきます。
    3. Query Options フィールドに、リソースに適用するクエリーを入力します。OData 構文を使用します。たとえば、$filter=startswith(name, 'N') は、N で始まる name フィールドを持つリソースで各エンティティーのメッセージを返します。

      Entity Key PredicateQuery Options の両方を指定できます。両方を指定すると、OData サービスは指定されたエンティティーを取得し、クエリーをそのエンティティーに適用します。たとえば、Entity Key PredicateUserName='russellwhyte'/Emails に設定し、Query Option$filter=contains($it,'example') に設定した場合、コネクションは以下のようなリクエストを作成します。

      https://services.odata.org/TripPinRESTierService/People(UserName='russellwhyte')/Emails?$filter=contains($it, 'example')

      サービスは、ドメイン example が含まれる Russell Whyte のメールアドレスをすべて返します。

    4. Filter Old Results チェックボックスを選択し、特定のメッセージを一度のみ取得します。
    5. メッセージのコレクションでなく、個別のメッセージをコネクションが返すようにするには、Split Results チェックボックスを選択します。

      Fuse Online は、フローに追加できる個別の分割ステップ (split step) および集約ステップ (aggregate step) も提供します。1 つ以上のステップで個別のメッセージを処理し、メッセージをコレクションに集約する場合は、Split Results チェックボックスを選択しないでください。代わりに、このチェックボックスを空のままにし、このコネクションの後にフローに分割ステップ (split step) を追加します。フローに集約ステップ (aggregate step) を使用する場合は分割ステップ (split step) が必要になります。

    6. Interval Before Polling Starts フィールドには、デフォルトの 1 秒を使用するか、コネクションが OData サービスのポーリングを開始するまでの経過期間を入力します。
    7. Delay フィールドには、デフォルトの 30 秒を使用するか、コネクションが OData サービスをポーリングする間隔を入力します。
    8. Backoff Idle Threshold フィールドには、デフォルトの 1 を使用するか、戻りデータがなくても許容されるポーリングの連続数を示します。このポーリング数を超えると、コネクションは後続のポーリングの間隔を長くします。コネクションは、Delay の値に Backoff Multiplier の値を掛けて、ポーリングの新しい間隔を決定します。

      たとえば、ポーリングの間隔 (Delay の値) がデフォルトの 30 秒である場合、Backoff Idle Threshold は 5 に設定され、Backoff Multiplier は12 に設定されます。ポーリングが 5 回連続でデータを返さなかった場合、コネクションは 360 秒 (30 x 12 ) 待機してからポーリングを再開します。コネクションは、ポーリングがデータを返すまで、360 秒間隔でポーリングを続行します。ポーリングがデータを返したら、コネクションはポーリング間隔を 30 秒に戻します。

    9. Backoff Multiplier フィールドには、デフォルトの 1 を使用するか、Backoff Idle Threshold に設定された値に達したときにポーリングの間隔を長くする乗数を整数で指定します。

      Backoff Multiplier にデフォルトの 1 を使用すると、連続して結果を返さなかったポーリングの数に関わらず、コネクションは指定の間隔でポーリングを続行します。

      コネクションはデータが返されないと自動的にポーリングの頻度を減らすことができるため、Backoff Idle Threshold および Backoff Multiplier に指定する値は、CPU オーバーヘッドの削減に便利です。

  6. Next をクリックします。

結果

インテグレーションに最初のコネクションが追加され、Fuse Online は最後のコネクションを選択するよう要求します。

実行中にコネクションが返すものは Entity Key Predicate および Query Options フィールドに指定した内容によって異なります。OData コネクションは以下を返すことができます。

  • エンティティーのコレクションまたはエンティティープロパティーのコレクション

    たとえば、リソースのすべての Person エンティティーであったり、すべての Person エンティティーのすべての Age プロパティーであったりします。コネクションはコレクションを 1 つのメッセージで返します。Fuse Online はコレクションに対して、フローで各後続ステップを 1 度実行します。しかし、Read アクションを設定するときに Split Results を選択すると、コネクションは独自のメッセージで各エンティティーまたは各プロパティーを返します。Fuse Online はフローで各後続ステップを一度各メッセージに対して実行します。

  • エンティティーまたはエンティティープロパティー

    たとえば、UserName プロパティーが Bob である Person エンティティーであったり、UserNameBob である Person エンティティーの Age プロパティーであったりします。コネクションは、フローの次のステップに渡すメッセージのエンティティーまたはエンティティープロパティーを返します。

次のステップ

インテグレーションの最後のコネクションと、インテグレーションに含まれるようにする他のコネクションを追加します。インテグレーションに必要なコネクションがすべて含まれ、OData コネクションがコレクションを返す場合、OData コネクションの後に分割ステップ (split step) を追加する必要があるか検討します。通常、インテグレーションは OData コネクションによって返されるデータをフローの後続のコネクションが使用できるフィールドにマップします。コレクションをマップすることもありますが、より多くの場合でターゲットフィールドにマップするためにコレクションを分割する必要があります。

OData コネクションの後、フローにデータマッパーステップを追加します。フローでの正確な場所は、フローが実行することによって異なります。たとえば、OData コネクションの後にベーシックフィルターステップを追加してから、データマッパーステップを追加することがあります。

20.3. OData サービスによって管理されるデータの更新、作成、および削除

インテグレーションでは、フローの途中で OData サービスによって管理されるリソースを更新したり、シンプルなインテグレーションを終了するために OData サービスによって管理されるリソースを更新することができます。これには、OData コネクションをフローの途中に追加するか、シンプルなインテグレーションの最後のコネクションとして追加します。

前提条件

  • OData コネクションが作成されている必要があります。
  • インテグレーションを作成または編集することになります。Fuse Online でインテグレーションに追加するよう要求されます。または、Fuse Online で最後のコネクションを選択するよう要求されます。

手順

  1. Add to Integration ページで、OData コネクションの追加先のプラス記号をクリックします。シンプルなインテグレーションの最後のコネクションを追加する場合は、このステップをスキップします。
  2. 使用する OData コネクションをクリックします。OData コネクションがエンティティーを更新または削除するときに、コネクションは何も返さないことに注意してください。OData コネクションがエンティティーを作成するとき、コネクションは新しいエンティティーを返します。
  3. Choose an action ページで、コネクションが実行するアクションを選択します。

    • Create はエンティティーを OData リソースに追加します。
    • Delete はエンティティーを OData リソースから削除します。
    • Update は OData リソースにあるエンティティーを変更します。
  4. 更新する OData リソースを選択し、アクションを設定します。

    更新する OData リソースの更新方法を理解することが重要になります。OData サービスのバッキングデータソースは、更新や競合解決のルールを決定します。たとえば、OData コネクションが新規エンティティーを作成しようとしたにも拘らず、その Predicate Key が指定されたエンティティーがすでに存在した場合にOData サービスは既存のエンティティーを上書きするか、既存のエンティティーのフィールドの一部を上書きするか、この操作を無視します。この状況で OData サービスがどのように動作するかを知るのはユーザー次第です。

  5. Next をクリックします。

結果

インテグレーションビジュアライゼーションで追加した場所にコネクションが表示されます。

次のステップ

OData コネクションの前にデータマッパーステップを追加します。エンティティーを更新するために、新しいエンティティーの作成に必要なデータを提供するソースフィールドをマップする必要があります。「インテグレーションデータを次のコネクションのフィールドにマッピング」を参照してください。