第7章 HTTP リクエスト (Webhook) によってトリガーされるインテグレーションの作成
HTTP GET
または POST
リクエストを Fuse Online が公開する HTTP エンドポイントに送信して、シンプルなインテグレーションの実行をトリガーできます。詳細は以下のトピックを参照してください。
7.1. Fuse Online Webhook を使用するための一般的な手順
HTTP GET
または POST
リクエストでインテグレーションの実行をトリガーするには、以下を行う必要があります。
-
GET
またはPOST
リクエストを Fuse Online に送信するかどうかを決定します。 - このリクエストを処理するようインテグレーションを計画します。
インテグレーションを終了するコネクションを作成します。
Fuse Online は、最初のコネクションとして使用する Webhook コネクションを提供します。
- インテグレーションに追加する他のコネクションを作成します。
インテグレーションを作成します。
- Webhook コネクションを最初のコネクションとして追加します。
最後のコネクションを追加した後、インテグレーションで必要な他のコネクションを追加します。最後のコネクションと途中のコネクションは、インテグレーションの実行をトリガーする HTTP リクエストを処理します。目的を達成するために最も適切な HTTP リクエストを選択および指定するのはユーザー自身です。これには以下を考慮してください。
- 取得または更新するデータが含まれるアプリケーションへのコネクションを追加します。
-
GET
リクエストは、キー/値パラメーターの指定に限定されます。 -
POST
リクエストは、XML や JSON インスタンスなどの任意のボディーを提供します。 -
Fuse Online は HTTP ステータスヘッダーのみを返し、データは返しません。そのため、
GET
リクエストによってトリガーされるインテグレーションや、データを取得せずにデータを更新するインテグレーションを定義できます。同様に、POST
リクエストによってトリガーされるインテグレーションや、データを更新せずにデータを取得するインテグレーションを定義することもできます。
Webhook コネクションの後にデータマッパーステップを追加します。
GET
リクエストでは、HTTP リクエストのパラメーターフィールドを次のコネクションのデータフィールドにマップします。POST
リクエストの場合、JSON インスタンス、JSON スキーマ、XML インスタンス、または SML スキーマを渡して、リクエストに出力データシェイプを指定した可能性があります。指定しなかった場合は、Webhook コネクションをインテグレーションの最初のコネクションとして追加します。指定しないと、Webhook コネクションの出力データタイプのデフォルトは JSON 形式になります。- インテグレーションに必要な他のステップを追加します。
- インテグレーションをパブリッシュし、Running 状態になるまで待ちます。
- インテグレーション概要ページに移動し、Fuse Online が提供する外部 URL をコピーします。
-
外部 URL を編集して、
GET
またはPOST
リクエストを作成します。 -
HTTP
GET
またはPOST
リクエストを Fuse Online に送信するアプリケーションを実装します。
7.2. HTTP リクエストがトリガー可能なインテグレーションの作成
HTTP GET
または POST
リクエストでインテグレーションの実行をトリガーするには、Webhook コネクションをインテグレーションの最初のコネクションとして追加します。
手順
- Fuse Online パネルの左側にある Integrations をクリックします。
- Create Integration をクリックします。
- Choose a connection ページで Webhook コネクションをクリックします。
Choose an action ページで Incoming Webhook アクションを選択します。
Webhook Configuration ページで、Fuse Online はこのインテグレーションのために生成した Webhook トークンを表示します。
HTTP リクエストを作成するとき、このトークンは URL の最後の部分になります。このインテグレーションをパブリッシュし、稼働状態になった後、Fuse Online はこのトークンが末尾にある Fuse Online 外部 URL を表示します。
- Next をクリックします。
Specify Output Data Type ページで以下を行います。
- Select Type フィールドをクリックし、JSON schema を選択します。
- Definition フィールドに、HTTP リクエストでパラメーターのデータタイプを定義する JSON スキーマを貼り付けます。「リクエストパラメーターを指定するための JSON スキーマ」を参照してください。
- Data Type Name フィールドに、このデータタイプの名前を指定します。これは任意のフィールドですが、名前を指定すると、データマッパーの Sources リストに表示されるため、フィールドを正しくマップしやすくなります。
- 必要に応じて、このデータタイプを区別するための情報を Data Type Description フィールドに入力します。
- Next をクリックします。
- 最後のコネクションをインテグレーションに追加します。
- 必要な他のコネクションを追加します。
- 必要な他のステップを追加します。
- 最初のコネクションの直後に、データマッパーステップを追加します。
- Publish をクリックし、インテグレーションの名前を付け、必要に応じて説明を追加した後、 Save and publish をクリックします。
7.3. Fuse Online による HTTP リクエストの処理方法
HTTP GET
または POST
リクエストを指定して、シンプルなインテグレーションの実行をトリガーできます。通常 GET
リクエストはデータを取得し、POST
リクエストはデータを更新しますが、いずれかのリクエストを使用して、いずれかのオペレーションを行うインテグレーションをトリガーできます。リクエストのパラメーターはすべてインテグレーションの次のコネクションにあるデータフィールドへのマッピングに利用できます。詳細は「リクエストパラメーターを指定するための JSON スキーマ」を参照してください。
Webhook コネクションは受信するデータのみをインテグレーションの次のコネクションに渡します。Fuse Online が HTTP リクエストを受信すると、以下を行います。
-
HTTP ステータスヘッダーを要求元に返します。リクエストがインテグレーションの実行を正常にトリガーした場合、Fuse Online の戻りコードは
201
になります。リクエストがインテグレーション実行のトリガーに失敗した場合、戻りコードは5xx
になります。 - 他のデータを要求元に返しません。ステータスヘッダーが含まれる 応答 の HTTP ボディーにはデータがありません。
- リクエストのデータをインテグレーションの次のコネクションに渡します。
そのため、GET
リクエストによってトリガーされるシンプルなインテグレーションや、データを取得せずにデータを更新するインテグレーションを定義できます。同様に、POST
リクエストによってトリガーされるシンプルなインテグレーションや、データを更新せずにデータを取得するインテグレーションを定義することもできます。
7.4. Fuse Online Webhook を呼び出す HTTP クライアントのガイドライン
HTTP リクエストを Fuse Online に送信するクライアントを実装する場合、実装は以下を行う必要があります。
-
GET
またはPOST
リクエストを作成する URL を作成するため、Fuse Online が提供する外部 URL に追加します。 -
URL リクエストに、
io:syndesis:webhook
JSON スキーマに準拠するデータタイプを持つ、HTTP ヘッダーとクエリーパラメーターの値を指定します。「リクエストパラメーターを指定するための JSON スキーマ」を参照してください。ヘッダーとクエリーパラメーターがこのデータタイプの指定に準拠する場合、パラメーターフィールドをインテグレーションの次のコネクションが処理できるフィールドにマップできます。 -
リクエストに成功した場合、返された成功コード
201
を処理します。 -
リクエストに失敗した場合、HTTP の
5xx
エラーコードを処理します。 - Fuse Online からの他の応答を想定しません。そのため、リクエストを送信しても戻りコード以外の戻りデータは直接要求元のクライアントに返されません。
7.5. リクエストパラメーターを指定するための JSON スキーマ
インテグレーションでは、通常 HTTP リクエストのヘッダーおよびクエリーパラメーターをインテグレーションの次のコネクションで処理できるデータフィールドにマップします。これを可能にするには、Webhook コネクションをインテグレーションに追加するときに、以下の構造を持つ JSON スキーマの出力データタイプを指定します。
{ "$schema": "http://json-schema.org/schema#", "id": "io:syndesis:webhook", "type": "object", "properties": { "parameters": { "type": "object", "properties": { 1 } }, "body": { "type": "object", "properties": { 2 } } } }
必要なデータ構造を追加するには、HTTP リクエストの JSON インスタンスで以下を行います。
HTTP クライアントが送信するデータはすべてインテグレーションで利用できますが、Webhook コネクションのデータシェイプがこの JSON スキーマに準拠する場合はクエリーパラメーターとボディーのコンテンツをマッピングに使用できます。
例は 「HTTP リクエストの指定方法」を参照してください。
7.6. HTTP リクエストの指定方法
以下の例は、Fuse Online Webhook に HTTP リクエストを指定する方法を示しています。
Webhook における HTTP ボディーのみの POST リクエストの例
Webhook コネクションで開始し、Fuse Online が提供するデータベースの Todo テーブルの行を作成するインテグレーションについて考えます。
このインテグレーションの作成中、Webhook の最初のコネクションを追加するときに {"todo":"text"}
がコンテンツにある JSON インスタンスで出力データタイプを指定します。
PostgresDB コネクションを最後のコネクションとして追加するとき、Invoke SQL アクションを選択し、この SQL ステートメントを指定します。
INSERT INTO TODO (TASK) VALUES (:#TASK)
データベースコネクションを追加した後、マッピングステップを追加します。
インテグレーションを保存し、パブリッシュします。実行中に Fuse Online が提供する外部 URL をコピーできます。
外部 URL の一部を理解するため、以下の URL の例を見てください。
https://i-webhook-to-db-myproject.192.168.64.4.nip.io/webhook/bvGvQdpq308BcHIQQYeysFOK4plFISmghNHkRyOOk3YppitvOd
値 | 説明 |
---|---|
| Fuse Online は常にこの値を URL の最初に挿入します。 |
| インテグレーションの名前。 |
| インテグレーションを実行している Pod が含まれる OpenShift namespace。 |
| OpenShift 用に設定された DNS ドメイン。これは、Webhook を提供している Fuse Online 環境を示しています。 |
| 各 Webhook コネクション URL に表示されます。 |
| Webhook コネクションをインテグレーションに追加するときに Fuse Online が提供する Webhook コネクショントークン。トークンは、URL を識別しにくくすることでセキュリティーを提供する無作為の文字列です。これにより、該当の送信者以外がリクエストを送信できないようにします。 リクエストでは、Fuse Online が提供するトークンを指定するか、独自のトークンを定義します。独自に定義する場合は、必ず簡単に推測できないものにしてください。 |
外部 URL が確認できたら、Fuse Online はインテグレーションの名前、OpenShift namespace の名前、および OpenShift DNS ドメインからホスト名を作成します。Fuse Online は使用できない文字を削除し、空白文字をハイフンに変換します。上記の外部 URL の例では、ホスト名は次のようになります。
https://i-webhook-to-db-myproject.192.168.64.4.nip.io
curl
を使用して Webhook を呼び出すには、コマンドを以下のように指定します。
curl -H 'Content-Type: application/json' -d '{"todo":"from webhook"}' https://i-webhook-to-db-myproject.192.168.64.4.nip.io/webhook/bvGvQdpq308BcHIQQYeysFOK4plFISmghNHkRyOOk3YppitvOd
-
-H
オプションは HTTPContent-Type
ヘッダーを指定します。 -
-d
オプションは、デフォルトで HTTP メソッドをPOST
に設定します。
このコマンドの実行により、インテグレーションがトリガーされます。データベースの最後のコネクションは新しいタスクをタスクテーブルに挿入します。これを確認するには、たとえば https://todo-myproject.192.168.64.4.nip.io で https://todo-myproject.192.168.64.4.nip.io
アプリケーションを表示し、Update をクリックします。from webhook
が新しいタスクとして表示されるはずです。
Webhook におけるクエリーパラメーターでの POST リクエストの例
この例では、前述の例と同じインテグレーションを使用します。
しかし、この例では以下のコンテンツを持つ JSON スキーマを指定して Webhook コネクションの出力データタイプを定義します。
{ "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#", "id": "io:syndesis:webhook", "properties": { "parameters": { "type": "object", "properties": { "source": { "type": "string" }, "status": { "type": "string" } } }, "body": { "type": "object", "properties": { "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } } } }
この JSON スキーマでは以下を行います。
-
id
がio.syndesis.webhook
に設定される必要があります。 -
parameters
セクションは HTTP クエリーパラメーターを指定する必要があります。 -
body
セクションはボディーのコンテンツを指定し、必要に応じて複雑に指定することができます。たとえば、入れ子のプロパティーやアレイを定義できます。
これは、Webhook コネクターがインテグレーションの次のステップのコンテンツを準備するために必要な情報を提供します。
curl
を使用して HTTP リクエストを送信するには、以下のようなコマンドを呼び出します。
curl -H 'Content-Type: application/json' -d '{"company":"Gadgets","email":"sales@gadgets.com","phone":"+1-202-555-0152"}'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg?source=web&status=new
Webhook コネクションがこのリクエストを受信すると、以下のような JSON インスタンスを作成します。
{ "parameters": { "source": "web", "status": "new" }, "body": { "company": "Gadgets", "email": "sales@gadgets.com", "phone": "+1-202-555-0152" } }
この JSON インスタンスが以下のマッピングを有効にします。
Webhook での GET の例
入力データを提供しない GET
リクエストでインテグレーションをトリガーするには、Webhook コネクションの出力データシェイプを、定義 '{}'
を持つ JSON インスタンスとして指定します。その後、クエリーパラメーターを指定しない以下の curl
コマンドを呼び出すことができます。
curl 'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg'
前述の POST
の例を変更して、クエリーパラメーターがありボディーはない GET
リクエストを送信します。Webhook コネクションの出力データシェイプを、以下の定義を持つ JSON スキーマとして指定します。
{ "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#", "id": "io:syndesis:webhook", "properties": { "parameters": { "type": "object", "properties": { "source": { "type": "string" }, "status": { "type": "string" } } } } }
以下の curl
コマンドは GET
リクエストを送信します。
curl 'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg?source=web&status=new'`