Webhook

Webhook は、HTTP POST リクエストを使用して複数のアプリケーション間でコールバックを渡し、複数のアプリケーションの相互対話を可能にするための広くサポートされている方法です。 詳細については、「Webhook に関する Wikipedia のページ」をご参照ください。 Webhook の一般的な使用法は、電子メールや SMS による通知の送信、ソーシャル メディアへのメッセージ投稿、スプレッドシートへのレコード自動書き込み、エンタープライズ データベースの更新などです。

ArcGIS Survey123 では、Webhook を設定して、調査の回答の送信時に作動させることができます。 たとえば、フィーチャ レイヤーへの情報送信に成功した後、Webhook を呼び出し、別のアクション (通知電子メールの送信、スプレッドシートへの調査コンテンツの付加、アラートの送信など) を実行できます。

職場に独自の Webhook プロバイダーが用意されていることもありますが、Microsoft Power Automate、Make (旧称 Integromat)、Zapier、tray.io など、さまざまなサードパーティのワークフロー サービスを利用できます。 これらはどれも、Survey123 を自動プロセスのトリガーとして組み込むために使用できます。 特に Microsoft Power Automate と Make はそれぞれ組み込みの Survey123 コネクタを備えており、困難を最小限に抑え、Survey123 Web サイトで Webhook を構成したり、ペイロード URL を入力することを必要とせずに、Survey123 を Webhook ワークフローに統合することができます。

注意:

調査の Webhook を作成または変更する場合は、変更を有効にするために、Survey123 フィールド アプリ内で調査を更新する必要があります。

Survey123 をワークフローのトリガーとして使用する方法は多数あります。 以下の 3 つのセクションでは、Webhook を設定し、回答が送信されたときに、特定の値で回答された質問を含む通知電子メールを送信する方法を示します。

このトピックの最後には、Webhook イベント ペイロードで使用できるすべてのプロパティが参照用に一覧されています。

Make での Webhook の設定

Make (旧称 Integromat) は、オンラインの自動化プラットフォームです。 無料のアカウントにサイン アップして、使用を開始します。 Make には、電子メール通知に添付ファイルを含めたり、スプレッドシートにレコードを追加したり、カレンダー アイテムを作成したりする際に使用できるテンプレートがあります。

1. https://www.make.com/ に移動し、サイン インします。
2. [Scenarios] ページで、[Create a new scenario] ボタンをクリックします。
3. 画面中央のモジュール アイコンをクリックします。 「Survey123」を検索して選択します。

   

4. [Watch survey] トリガー モジュールを選択します。

   このモジュールは、調査の回答が送信されるたびにシナリオを実行するように設計されています。

   [Watch survey] モジュールを構成するポップアップが表示されます。

   ヒント:

   [Create report] モジュールを使用すると、調査の回答のレポートを生成できます。

5. [Add] をクリックして、Webhook の名前を入力します。

   この名前は、Webhook を構成している調査では一意である必要があります。

6. Survey123 モジュールを Make で初めて使用する場合は、ArcGIS 組織サイトへの接続を設定してください。 これを行う必要があるのは 1 回だけです。今後使用するために、Make が情報を保存します。 [Connection] の下の [Add] をクリックして、接続に「ArcGIS」という名前を指定します。
   • ArcGIS Online に接続するには、[Save] をクリックして ArcGIS 組織にサイン インします。
   • ArcGIS Enterprise に接続するには、ポータルに Make を登録します。 詳細については、「Survey123 Tricks of the Trade: Make」ブログ記事をご参照ください。
7. ArcGIS 組織サイトから、接続先の調査を選択します。

   

8. Webhook に含めるオプションを検討し、[Save] をクリックします。

   すべての高度な設定で、デフォルト値の [Yes] をそのままにすることをお勧めします。それによって、Webhook をカスタマイズするときに、最高の柔軟性が得られます。

9. [OK] をクリックします。

   Webhook が作成され、[Watch survey] モジュールが構成されます。

10. [Watch survey] モジュールの右側にある [Add another module] ボタンをクリックして、別のモジュールを接続します。

    

11. 「Email」を検索し、[Email] モジュールを選択します。
12. [Send an Email] 操作を選択します。
13. このモジュールを Make で初めて使用する場合、[Add] をクリックして電子メール アカウントへの接続を設定する必要があります。 接続タイプを選択し、アカウントにサイン インします。

    これを行う必要があるのは 1 回だけです。今後使用するために、Make が接続を保存します。

14. 受信者の電子メール アドレスを追加します。

    これは、トリガーされた電子メールの送信先になる電子メール アドレスです。

15. 件名テキスト ボックスをクリックします。 表示されるモジュール設定パネルを使用し、調査のフィールドを選択して電子メールの件名を作成します。
16. コンテンツ テキスト ボックスをクリックします。 表示されるモジュール設定パネルを使用し、調査のフィールドを選択して電子メールのコンテンツを作成します。 HTML を使用してコンテンツの書式を設定できます。
17. [OK] をクリックします。

    このシナリオでは、ある質問に対して特定の回答が出された場合に電子メールを送信する必要があるため、次にフィルターを指定します。

18. 2 つのモジュールの間にあるツール ボタンをクリックし、[Set up a filter] を選択します。

    

19. [Condition] テキスト ボックスをクリックし、フィルターで使用するフィールドを調査から選択します。

    

20. 条件の演算子を選択します。 この場合、デフォルトの [Equal to] を選択します。
21. 条件の値を入力して [OK] をクリックします。
22. [Save] をクリックして、シナリオを保存します。

    必要に応じて、[Run once] をクリックし、Webhook をテストすることができます。 [Run once] をクリックした後に、Survey123 を開いて調査を送信し、調査の回答がフィルターの条件を確実に満たすようにします。 受信者がメールを受信したことを確認します。

23. ページの左下にある切り替えボタンを使用して、シナリオをアクティブにします。 スケジュールを [Immediately] に設定することで、調査の回答が送信されるたびにシナリオが実行されるようにします。

    Survey123 を Make シナリオのトリガーとして使用するその他の方法については、「Survey123 の統合」をご参照ください。

Microsoft Power Automate での Webhook の設定

Microsoft Power Automate は、Microsoft Office 365 プラットフォームで提供される Webhook サービスです。

注意:

Power Automate でのフローの作成に使用される ArcGIS Online の認証情報は 2 週間後に自動的にサイン アウトします。 Power Automate で予期される調査を参照できない場合は、Survey123 データ接続がアクティブであることを確認します。 詳細については、技術情報記事「ドロップダウン リストに調査が表示されない」をご参照ください。

次の手順は、ArcGIS Online に公開された調査に対して組み込みの Survey123 コネクタを使用するフローを設定する方法を示しています。 ArcGIS Enterprise に公開された調査で Power Automate を使用するには、カスタムのコネクタを設定する必要があります。 詳細については、「How To: Create an ArcGIS Survey123 connector for Microsoft Power Automate for use with ArcGIS Enterprise」の技術情報記事をご参照ください。

1. Microsoft Power Automate を開きます。
2. ページのサイド メニューから [作成] を選択します。
3. [一から開始] オプションから [自動化したクラウド フロー] を選択します。

   [自動化したクラウド フローを構築する] ダイアログ ボックスが表示されます。

4. フローに名前を付けます。

   次に、トリガーを選択します。

5. 検索バーに「Survey123」と入力します。 [アンケートの回答が送信されたとき] を選択します。

   

6. [作成] をクリックします。
7. Microsoft Power Automate で初めてこのコネクタを使用する場合は、[サイン イン] をクリックし、ArcGIS 組織の認証情報を使用してサイン インします。

   これを行う必要があるのは 1 回だけです。今後使用するために、Microsoft Power Automate が接続を保存します。

8. 調査のドロップダウン リストから、Webhook に使用する調査を選択します。

   これで、Webhook のトリガーを設定しました。 ただし、このトリガーでアクションを実行する Webhook の場合、プロセスに追加のステップが必要となります。

   このフローでは、ある質問に対して特定の回答が出された場合に電子メールを送信する必要があるため、次に条件を指定します。

9. [新しいステップ] ボタンをクリックした後、[アクション] セクションの上部にある [条件] を選択します。

   

10. 左端のテキスト ボックスをクリックして、調査の質問またはプロパティを選択するためのダイアログ ボックスを開きます。 調査の条件付けに使用する調査の質問を選択します。
11. 中央のテキスト ボックスは、トリガーの条件を選択するドロップダウン メニューです。 正確な応答を探すため、[次の値に等しい] を選択します。
12. 右端のテキスト ボックスに、通知を送信する質問に対する値を入力します。

    条件が満たされた場合にのみ電子メールを送信できます。

13. [はいの場合] ボックスで [アクションの追加] をクリックします。 [いいえの場合] ボックスは、空白のままにしておきます。

    複数のメール サービスがコネクタを持っており、このフローでそれらのメール サービスを使用できます。

14. この演習では、[Office 365 Outlook - メールの送信 (V2)] を選択します
15. 認証情報がまだ保存されていない場合は、認証情報を使用してメール サービスにサイン インします。
16. 電子メールの [宛先]、[件名]、[本文] フィールドに入力します。

    テキスト ボックスを選択したときに表示される [動的コンテンツ] ダイアログ ボックスでは、必要に応じて調査の回答のコンテンツを挿入できます。

17. 電子メールが完成したら、[保存] をクリックします。

Webhook が完成し、デフォルトでアクティブになります。 これで、所定の条件を満たす調査の回答が送信されるたびに、Webhook が実行されます。

ヒント:

[レポートの作成] アクションを使用すると、調査の回答のレポートを生成できます。

Survey123 Web サイトでの Webhook の構成

Survey123 Web サイトで Webhook を設定するには、次の手順を実行します。

1. [調査] ページで調査のパネルの右下にあるメニューから [設定] タブを選択します。
2. 左側のメニューから [Webhook] セクションを選択します。

   このページでは、Webhook を設定したり、設定済みのすべての Webhook にアクセスしたりできます。 Survey123 で Webhook を 1 つも設定していない場合、このページは空です。

3. [Webhook の追加] をクリックします。

   Webhook が調査と対話する方法を設定できる新しいページが表示されます。

   

4. Webhook の名前を指定します。これは、今後 Webhook の識別に使用されます。
5. [ペイロード URL] は、調査情報が送信される場所です。 これは、外部の Webhook サービスによって提供される必要があります。

   Microsoft Power Automate や Make などのサービスを使用して Webhook を作成する場合は、ペイロード URL が自動的にこのページに入力されます。 Zapier や FME サーバーなどの他のサービスでは、このページにコピーするペイロード URL が提供されます。 他のアプリでは、場合によっては Webhook を待機するための専用サービスを作成する必要があります。

6. トリガー イベントは、Webhook を呼び出す特定のアクションを示します。 [新しいレコードが送信されました] を選択します。
7. [イベント データ] では、ペイロードに含める調査の情報を選択できます ([調査情報]、[サーバーの応答]、[送信されたレコード]、[ユーザー情報]、[ポータル情報])。 [調査情報] オプションと [送信されたレコード] オプションをオンにします。
8. [ステータス] 切り替えボタンによって、Webhook が保存時にアクティブになるかどうかが決まります。 [オン] のままにします (デフォルト)。
9. [保存] をクリックします。

Webhook を使用する準備が整い、調査の回答が送信されるたびに Webhook が実行されます。 Webhook プロバイダーに設定されるルールによって、特定の基準が満たされた場合にだけ電子メールが送信されるようにすることができます。

イベント ペイロード プロパティ

Webhook イベントはプロパティのペイロードを JSON オブジェクトとして送信します。 ペイロードの内容は調査によって異なります。 以下の表に、JSON オブジェクトに含まれる一般的なプロパティを一覧します。

プロパティ	説明
eventType	イベントのタイプ。 値には addData または editData を使用できます。
portalInfo	調査がホストされている ArcGIS 組織に関する情報。 次のプロパティが含まれています。 url token
surveyInfo	Webhook を生成した調査に関する情報。 次のプロパティが含まれています。 formItemId formTitle serviceItemId serviceUrl
userInfo	調査を送信したユーザーの ArcGIS 組織アカウントに関する情報。 次のプロパティが含まれています。 username firstName lastName fullName email

以下のプロパティは調査およびイベントのタイプに応じて異なります。

プロパティ	説明
applyEdits	調査によって送信された「編集の適用」ペイロード。 eventType が addData の場合、adds が含まれます。 eventType が editData の場合、updates が含まれます。 新しい繰り返しレコードを追加する場合は adds も含まれます。
response	applyEdits 操作からの応答。 操作によって作成されたフィーチャの Global ID、および操作が成功したかどうかが含まれます。
feature	送信された調査レコード。 次のプロパティが含まれています。 attributes geometry layerInfo result repeats 注意: repeats 配列内の各オブジェクトは、attributes、geometry、layerInfo、result、repeats、attachments を持つ feature です。 attachments id globalId name contentType size keywords url parentObjectId