Webhook を使用したワークフローの作成と呼び出し
外部システムからワークフローを開始するには、Webhook を使用します。Webhook によって提供される URL をその他のシステムが呼び出すことで、ThingWorx サーバーはワークフローを開始できます。
Webhook の追加
ワークフローに Webhook を追加するには、次の手順を完了します。
1. Webhook を追加するワークフローを開きます。
2. ![](../../../ThingWorx/images/StartIcon.png)
をクリックしてから
![](../../../ThingWorx/images/SettingsIcon.png)
をクリックするか、
![](../../../ThingWorx/images/StartIcon.png)
をダブルクリックします。トリガーウィンドウが表示されます。
3. 「Webhook」を選択します。Webhook のコンフィギュレーションウィンドウが開きます。
ワークフローの実行に使用する URL が「URL」フィールドに表示されます。
4. Webhook を非同期で実行するには、「非同期」チェックボックスをオンにします。
Webhook を非同期で実行した場合、Webhook の呼び出しはワークフローが完了するのを待たずにただちに返ります。
5. 「入力」セクションで「追加」をクリックし、Webhook が呼び出されたときにワークフローに渡される入力パラメータを指定します。パラメータごとに、以下の情報を入力します。
a. 「名前」 - 入力パラメータの名前。
b. 「説明」 - 入力パラメータの説明。
c. 「ベースタイプ」 - 入力パラメータのベースタイプ。
複数の入力パラメータを追加するには、
「追加」をクリックします。追加した入力パラメータを削除するには、
![](../../../ThingWorx/images/DeleteIcon.png)
をクリックします。
6. 「完了」をクリックします。
Webhook をワークフローに定義した後で、ワークフローからの戻り値パラメータを定義できます。外部システムは、ワークフローの実行結果から結果を取得して処理できます。外部システムで戻り値パラメータを取得するには、Webhook を同期実行するように定義する必要があります。
戻り値パラメータを定義するには、次の操作を行います。
1. ![](../../../ThingWorx/images/StopIcon.png)
をクリックしてから
![](../../../ThingWorx/images/SettingsIcon.png)
をクリックするか、
![](../../../ThingWorx/images/StopIcon.png)
をダブルクリックします。「出力」ウィンドウが開きます。
2. 返すデータの「ベースタイプ」を選択します。
3. 「データ」フィールドで、ワークフローに含まれる最後の操作の出力をマッピングして、Webhook に値を返します。
4. 「完了」をクリックします。
Webhook の呼び出し
Webhook をワークフローに定義した後は、Webhook の URL を使用してワークフロー実行を開始します。HTTP リクエストで、ThingWorx REST API を呼び出す標準メカニズムを使用します。
HTTP リクエストの設定に関する情報を、次のテーブルに示します。
HTTP リクエストのコンポーネント | 値 |
---|
メソッド | POST |
ヘッダー | • Accept: application/json • Content-Type: application/json • Authorization: Basic <エンコードされたユーザー名/パスワード> または appkey: <事前に定義されたアプリケーションキー> | Webhook 認証が最終的に期限切れになるようにするため、適切な有効期限のアプリケーションキーを使用することをお勧めします。 |
|
ボディ | application/json - ワークフローへの入力から成る JSON ペイロード。ここで、名前は Webhook に指定されている入力パラメータ名と一致していなければなりません。 たとえば、ワークフローに Webhook と次の 2 つの入力パラメータが定義されており、 • Name: "param1", Type: "STRING" • Name: "param2", Type: "XML" STRING 出力を返す場合、HTTP リクエストのボディ内の JSON ペイロードは以下のようになります。 {"param1": "This is a string parameter", "param2": "<xml><field1>helloworld</field1></xml>"} |
テストのために、Postman や curl などのツールを使用して、Webhook を含むワークフローを呼び出すことができます。Webhook を呼び出すには、次の例を使用できます。
curl --request POST \
--url https://<server>/Thingworx/Things/FlowThing/Services/webhook_flow \
--header 'Accept: application/json' \
--header 'Authorization: Basic <encoded_user_name_password>'
--header 'Content-Type: application/json' \
--header 'cache-control: no-cache' \
--data '{ "param1": "This is a string parameter", "param2": "<xml><field>helloworld</field></xml>"}
Webhook が非同期実行するように設定されている場合、Webhook を呼び出すリクエストはただちに返り、HTTP 応答でワークフローからのデータは返されません。
Webhook が同期実行するように設定されている場合、Webhook を呼び出すリクエストはワークフローが完了するまで待機し、HTTP 応答でワークフローからのデータが返されます。応答フォーマットは ThingWorx サービス呼び出しの規則に従い、HTTP リクエスト内の「承認」ヘッダーによって決まります。
この場合、JSON で以下のような応答が返されます。
{
"dataShape": {
"fieldDefinitions": {
"result": {
"name": "result",
"description": "result",
"baseType": "STRING",
"ordinal": 0,
"aspects": {}
}
}
},
"rows": [
{
"result": "<workflow result here>"
}
]
}