Webhook

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

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

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

注意:

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

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

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

Integromat での Webhook の設定

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

  1. https://www.integromat.com/ に移動し、サイン インします。
  2. [Create a new scenario] ボタンをクリックします。
  3. Survey123」を検索して選択します。 [続行] をクリックします。

    Survey123 モジュールは、シナリオではお気に入りとしてリスト表示されます。

  4. 画面中央のモジュール アイコンをクリックして、メニューから Survey123 を選択します。

    Survey123 モジュールを追加します。

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

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

    シナリオ アイコンの色が変化し、Survey123 モジュールを構成するのに役立つウィザードが表示されます。

    ヒント:

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

  6. [追加] をクリックして、Webhook の名前を入力します。

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

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

    調査の Webhook

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

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

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

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

  11. [Survey123] モジュールの右側にある [別のモジュールの追加] ボタンをクリックして、別のモジュールを接続します。

    別のモジュールを追加します。

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

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

  15. 受信者の電子メールを追加します。

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

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

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

  19. 2 つのモジュールの間にあるツール ボタンをクリックし、[フィルターの設定] を選択します。

    フィルターをシナリオに追加します。

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

    フィルターを定義します。

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

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

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

Survey123 をワークフローのトリガーとして使用するその他の方法については、「Integromat Survey123 の統合」をご参照ください。

Microsoft Power Automate での Webhook の設定

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

注意:

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

  1. Microsoft Power Automate を開きます。
  2. ページのサイド メニューから [Create] を選択します。
  3. [Start from blank] オプションから [Automated cloud flow] を選択します。

    [Build an automated cloud flow] ダイアログ ボックスが表示されます。

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

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

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

    Microsoft Power Automate の Survey123 コネクタ

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

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

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

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

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

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

    Microsoft Power Automate の条件 UI

  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 が調査と対話する方法を設定できる新しいページが開きます。

    Survey123 Web サイトでの [Webhook の追加] ページ

  4. Webhook の名前を指定します。これは、今後 Webhook の識別に使用されます。
  5. [ペイロード 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

調査によって送信された「編集の適用」ペイロード。

eventTypeaddData の場合、adds が含まれます。

eventTypeeditData の場合、updates が含まれます。 新しい繰り返しレコードを追加する場合は adds も含まれます。

response

applyEdits 操作からの応答。 操作によって作成されたフィーチャの Global ID、および操作が成功したかどうかが含まれます。

feature

送信された調査レコード。 次のプロパティが含まれています。

  • attributes
  • geometry
  • layerInfo
  • result
  • repeats
    注意:

    repeats 配列内の各オブジェクトは、attributesgeometrylayerInforesultrepeatsattachments を持つ feature です。

  • attachments
    • id
    • globalId
    • name
    • contentType
    • size
    • keywords
    • url
    • parentObjectId