Webhook

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

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

注意:

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

職場に独自の Webhook プロバイダーが用意されていることもありますが、Microsoft Power Automate、Make、Zapier、tray.io など、さまざまなサードパーティーのワークフロー サービスを利用できます。 これらはどれも、Survey123 を自動プロセスのトリガーとして組み込むために使用できます。

Microsoft Power Automate と Make には、Survey123 で使用する Webhook の作成を支援するワークフロー コンポーネントも含まれています。

Survey123 でサポートされる Webhook のタイプ

Survey123 では、次の 2 種類の Webhook がサポートされています。

• フィーチャ レイヤー Webhook - 調査のフィーチャ レイヤーまたはフィーチャ レイヤー ビューに格納されてトリガーされます。
• Survey123 Webhook - 調査のフォーム アイテムに格納されて、フィールド アプリまたは Web アプリによってトリガーされます。

Microsoft Power Automate には、フィーチャ レイヤー Webhook または Survey123 Webhook の設定に役立つ ArcGIS コネクターが含まれています。 詳細については、「ArcGIS コネクター」をご参照ください。 Survey123 Webhook の設定に役立つ次のワークフロー コンポーネントは引き続き使用できますが、今後は更新されません:

• Microsoft Power Automate - Survey123 コネクター
• Make - Survey123 モジュール

Webhook の設定方法の例

Survey123 をワークフローのトリガーとして使用する方法は多数あります。 このセクションの最初の 3 つの例では、同じシナリオ (Webhook を設定し、回答が送信されたときに、特定の値で回答された質問を含む通知電子メールを送信する) を使用していますが、それぞれに異なるサードパーティーのワークフロー コンポーネントまたは Webhook のタイプがあります。 最後の例では、(Microsoft Power Automate コネクターまたは Make モジュールを使用しないで) カスタム Webhook が作成されていることを前提としており、Webhook を Survey123 に追加する方法について説明しています。

以下の例をご参照ください。

• Microsoft Power Automate でのフィーチャ レイヤー Webhook の設定
• Microsoft Power Automate での Survey123 Webhook の設定
• Make での Survey123 Webhook の設定
• Survey123 Web サイトでの Webhook の追加

Microsoft Power Automate でのフィーチャ レイヤー Webhook の設定

Microsoft Power Automate でフィーチャ レイヤー Webhook を設定するには、次の手順を実行します:

注意:

Power Automate でのフローの作成に使用される ArcGIS Online の認証情報は 2 週間後に自動的にサイン アウトします。 Power Automate で予期される調査を参照できない場合は、Survey123 データ接続がアクティブであることを確認します。 詳細については、「簡単なヒント: ArcGIS Connectors for Power Automate のリフレッシュ トークンを有効に保つ」ブログ記事をご参照ください。

ArcGIS コネクターまたは ArcGIS Enterprise コネクターを使用して Microsoft Power Automate でのフローを設定するには以下の手順を実行します。 以前に Survey123 コネクターを使用してフローを作成した場合、そのフローは引き続き機能しますが、新しい機能は ArcGIS コネクターおよび ArcGIS Enterprise コネクターにのみ追加されます。 詳細については、「ArcGIS Connectors for Power Automate の Survey123 トリガーとアクション」ブログ記事をご参照ください。

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

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

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

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

5. 検索バーに「ArcGIS」と入力し、このワークフローでトリガーとして [フィーチャ レイヤーでレコードが作成されたとき] を選択します。
6. [作成] をクリックします。
7. ArcGIS 組織の認証情報を使用してサイン インし、監視するフィーチャ レイヤーを選択します。

   送信先のフィーチャ レイヤーまたはフィーチャ レイヤー ビューを選択する必要があります。

8. このワークフローに [フィーチャ レイヤーから変更、更新、または削除を取得する] アクションを追加します。
   1. [変更を取得] の入力として [URL の変更] を設定します。
   2. [フィーチャ レイヤー ID] の入力として [layerId] を設定します。
9. [Office 365 Outlook - メールの送信 (V2)] を選択します。
10. 認証情報がまだ保存されていない場合は、認証情報を使用してメール サービスにサイン インします。
11. 電子メールの [宛先]、[件名]、[本文] フィールドに入力します。

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

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

Webhook が完成し、デフォルトでアクティブになります。 これで、30 秒ごとに Webhook が実行されます。

Microsoft Power Automate での Survey123 Webhook の設定

Microsoft Power Automate で Survey123 Webhook を設定するには、次の手順を実行します:

注意:

Power Automate でのフローの作成に使用される ArcGIS Online の認証情報は 2 週間後に自動的にサイン アウトします。 Power Automate で予期される調査を参照できない場合は、Survey123 データ接続がアクティブであることを確認します。 詳細については、「簡単なヒント: ArcGIS Connectors for Power Automate のリフレッシュ トークンを有効に保つ」ブログ記事をご参照ください。

ArcGIS コネクターまたは ArcGIS Enterprise コネクターを使用して Microsoft Power Automate でのフローを設定するには以下の手順を実行します。 以前に Survey123 コネクターを使用してフローを作成した場合、そのフローは引き続き機能しますが、新しい機能は ArcGIS コネクターおよび ArcGIS Enterprise コネクターにのみ追加されます。 詳細については、「ArcGIS Connectors for Power Automate の Survey123 トリガーとアクション」ブログ記事をご参照ください。

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

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

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

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

5. 検索バーに「ArcGIS」と入力し、[アンケートの回答が送信されたとき] を選択します。
6. [作成] をクリックします。
7. ArcGIS 組織の認証情報を使用してサイン インします。
8. 調査のドロップダウン リストから、Webhook に使用する調査を選択します。

   これで、Webhook のトリガーを設定しました。ただし、このトリガーでアクションを実行する Webhook の場合は、追加の手順があります。

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

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

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

13. [はいの場合] ボックスで [アクションの追加] をクリックします。

    [いいえの場合] ボックスは、空白のままにしておきます。

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

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

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

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

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

ヒント:

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

Make での Survey123 Webhook の設定

Make で Survey123 Webhook を設定するには、次の手順を実行します:

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 組織サイトへの接続を設定してください。 [Connection] の下の [Add] をクリックして、接続に「ArcGIS」という名前を指定します。

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

   • 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 の統合」をご参照ください。

Survey123 Web サイトでの Webhook の追加

Survey123 Webhook またはフィーチャ レイヤー Webhook を Web サイトで追加できます。 フィーチャ レイヤー Webhook を設定する手順を次に示します。 Survey123 Webhook は同じですが、[イベント データ] オプションがイベント ペイロード プロパティに追加されています。

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

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

3. [Webhook の追加] をクリックして、[フィーチャ レイヤー Webhook の追加] を選択します。

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

4. Webhook の名前を指定します。これは、今後 Webhook の識別に使用されます。

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

トリガー イベントは、Webhook を呼び出す特定のアクションを示します。

5. [新しいレコードが送信されました] を選択します。
[ステータス] 切り替えボタンによって、Webhook が保存時にアクティブになるかどうかが決まります。
6. [オン] のままにします (デフォルト)。
7. [保存] をクリックします。

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

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

Webhook イベントはプロパティのペイロードを JSON オブジェクトとして送信します。 ペイロードの内容は使用される Webhook のタイプと調査によって異なります。

フィーチャ レイヤー Webhook には addData または editData のみが含まれています。 詳細については、「フィーチャ レイヤー Webhook のペイロード」をご参照ください。

Survey123 Webhook にはイベントのタイプと追加のプロパティが含まれています。 以下の表に、Survey123 Webhook の JSON オブジェクトに含まれる一般的なプロパティを示します:

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

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

プロパティ	説明
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