Webhook は、アプリケーションが他のアプリケーションに、イベントによって発生する情報を提供できるようにするメカニズムです。ArcGIS Enterprise ポータル管理者は、Webhook を作成、管理、および構成できます。Webhook を構成することで、ポータル アイテム、グループ、およびユーザーに関連付けられたイベントが発生した際に、自動的に通知を受けることができます。Webhook がトリガーされると、ユーザー定義の一意のペイロード URL に対して HTTP リクエストが送信され、イベントに関する情報が提供されます。
主要な用語
以下に、Webhook の主要な用語を示します。
- トリガー イベント - Webhook をトリガーするために設定した操作。たとえば、組織内で特定のグループが更新されたときや、アイテムが共有されたときに、Webhook がトリガーされるように構成できます。Webhook は、複数のトリガー イベントを持つことができます。
- ペイロード - 指定したイベントが発生した後に Webhook によって配信されるトリガー イベント データ。この情報は JSON 形式です。詳細については、下記の「ペイロード」をご参照ください。
- ペイロード URL - ペイロードの送信先。ペイロード URL は、Microsoft Power Automate、Zapier、IFTTT などのサービスを使用して作成できます。選択したプラットフォームを使用して、独自のカスタム Web サービス エンドポイントを作成することもできます。
使用例
Webhook を使用することで、システム間でワークフローを統合できます。組織での Webhook の活用には、さまざまな方法があります。
ArcGIS Enterprise でのアクティビティの監視
Webhook を使用して、ArcGIS Enterprise 内のアクティビティを監視できます。たとえば、特定のアイテムに関連付けられているすべてのイベントに登録することができます。アイテムのプロパティが更新されると Webhook がトリガーされ、HTTPS リクエストによって、イベントの内容を示したデータを含むペイロードが配信されます。このペイロードの配信先を決定することで、情報の受信時にその内容に応じたアクションをとることができます。
サポートされているトリガー イベント
Webhook を作成する際、トリガー イベントに登録します。これらのイベントはポータルでの操作となるため、操作に対する URI を Webhook 構成で指定する必要があります。以下のサブセクションでは、使用できるトリガー イベントとそれに関連付けられた URI について説明します。
アイテム
更新できるアイテムのプロパティはアイテム タイプによって異なり、/ update 操作をトリガーする一意のアクションがあります。たとえば、アイテムが Web マップの場合、タグの更新、ポップアップの構成、ベースマップの変更などはすべて Webhook をトリガーする更新イベントになります。
次の表に、Web マップ、Web アプリ、レイヤー、パッケージ、PDF ドキュメントなど、サポートされているポータル アイテムのトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
全アイテムに対するすべてのトリガー イベント | /items |
ポータルへのアイテムの追加 | /items/add |
特定のアイテムに対するすべてのトリガー イベント | /items/<itemID> |
特定のアイテムの削除 | /items/<itemID>/delete |
特定のアイテムのプロパティの更新 | /items/<itemID>/update |
アイテムの移動、またはアイテムの所有権の変更 | /items/<itemID>/move |
特定のアイテムの公開 | /items/<itemID>/publish |
特手のアイテムの共有 | /items/<itemID>/share |
特定のアイテムの共有解除 | /items/<itemID>/unshare |
グループ
グループ設定に対する一般的な変更はすべて更新として扱われます。たとえば、グループのアクセス権限を変更すると更新イベントが発生します。
次の表に、グループに関連付けられているトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
全グループに対するすべてのトリガー イベント | /groups |
グループの追加 | /groups/add |
特定のグループに対するすべてのトリガー イベント | /groups/<groupID> |
特定のグループの更新 | /groups/<groupID>/update |
特定のグループの削除 | /groups/<groupID>/delete |
特定のグループに対する [削除の防止] の有効化 | /groups/<groupID>/protect |
特定のグループに対する [削除の防止] の無効化 | /groups/<groupID>/unprotect |
特定のグループへのユーザーの招待 | /groups/<groupID>/invite |
特定のグループへのユーザーの追加 | /groups/<groupID>/addUsers |
特定のグループからのユーザーの削除 | /groups/<groupID>/removeUsers |
特定のグループ内のユーザー ロールの更新 | /groups/<groupID>/updateUsers |
ユーザー
更新イベントは、ユーザー プロファイルが変更されるたびにトリガーされます。ただし、ユーザー ロール、ユーザー タイプ、またはライセンスに加えられた変更は、ユーザー プロファイルの更新とは見なされません。
次の表に、ユーザーに関連付けられているトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
ポータル内の全ユーザーに対するすべてのトリガー イベント | /users |
組織サイトへのユーザーの追加 | /users/add |
特定のユーザーに関連付けられているすべてのトリガー イベント | /users/<username> |
特定のユーザーがポータルにサイン インした | /users/<username>/signIn |
特定のユーザーがポータルからサイン アウトした | /users/<username>/signOut |
特定のユーザーの削除 | /users/<username>/delete |
特定のユーザー プロファイルの更新 | /users/<username>/update |
特定のユーザー アカウントの無効化 | /users/<username>/disable |
特定のユーザー アカウントの有効化 | /users/<username>/enable |
ペイロード
Webhook がトリガーされると、ペイロードが JSON 形式で特定のペイロード URL に配信されます。各イベントは、そのイベントに関連する情報を含む同様の JSON スキーマに従います。
| キー | 種類 | 説明 |
|---|---|---|
| webhookName | 文字列 | ペイロードを配信した Webhook の名前。 |
| webhookId | 文字列 | ペイロードを配信した Webhook の ID。 |
| portalURL | 文字列 | Webhook が登録されているポータルの URL。 |
| when | timestamp | ペイロードが配信された時刻。 |
| username | 文字列 | イベントをトリガーしたユーザー。 |
| userId | 文字列 | イベントをトリガーしたユーザーの ID。 |
| when | timestamp | イベントが発生した時刻。 |
| operation | 文字列 | ユーザーが実行した操作。以下のとおりです。
|
| source | 文字列 | 操作が実行されたアイテム タイプ。item、group、または user のいずれかです。 |
| id | 文字列 | 操作が実行されたソース アイテムの ID。 |
| properties | オブジェクト | イベントに関連付けられているその他のプロパティ。以下のとおりです。
|
ペイロード URL
ペイロード URL は、Webhook を作成する際にユーザーが指定する必要があります。この URL により、ペイロードの配信先が定義されます。ペイロードは HTTPS POST リクエストを介して配信されるため、HTTPS で通信し、ポータルからアクセスできるように Webhook レシーバーを構成する必要があります。ペイロードを含むカスタム ワークフローを構成する際、Microsoft Power Automate、Zapier、IFFT などの複数の Web サービスを使用できます。たとえば、Microsoft Power Automate がペイロードを受信した場合に、ペイロードを解析および書式設定し、電子メール エイリアスに送信するようなワークフローを作成できます。また、ペイロードを受信するように Web サービスを構築およびカスタマイズすることもできます。インターネット アクセスを制限している組織の場合、ペイロードを受信するためのカスタム Web サービスを構築することをお勧めします。すぐに使える Java サーブレットについては、当社の Enterprise SDK サンプルをご参照ください。
ペイロードの例
以下は、特定のグループが更新されたことを示すサンプル ペイロードです。
{
"info": {
"webhookName": "Group monitoring",
"webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
"portalURL": "https://machineURL/portal/",
"when": 1543192196521
},
"events": [{
"username": "administrator",
"userId": "173dd04b69134bdf99c5000aad0b6298",
"when": 1543192196521,
"operation": "update",
"source": "group",
"id": "173dd04b69134bdf99c5000aad0b6298",
"properties": {}
}]
}
Webhook の作成
Webhook は、ArcGIS Portal Directory を介してのみ管理できます。Webhook を作成するには、次の手順に従います。
- ArcGIS Portal Directory に移動します。https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- 管理者としてサイン インします。
Webhook は管理者のみが作成および管理できます。
管理者ユーザー ページが表示されます。
- [Org ID] ハイパーリンクをクリックするか、以下のフォームのリクエストを行い、[Portal] → [Self] リソース ページに移動します。https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- ページの下部にスクロールし、[Child Resources] の下にある Webhooks に移動します。https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
- [Supported Operation] で、Create Webhook を選択します。
- Webhook のパラメーターを指定します。
これらのパラメーターの詳細については、Webhook の REST API ドキュメントをご参照ください。
作成した Webhook は、他の Webhook の下に表示されます。https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
Webhook の管理
次のフォームでリクエストを送信することで、ArcGIS Portal Directory を通じて Webhook を管理できます。
https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>
Webhook の管理でサポートされている操作は次のとおりです。
- Update Webhook - Webhook のパラメーターを更新します。指定した Webhook の名前、ペイロード URL、またはトリガー イベントを更新できます。
- Delete Webhook - ポータルから Webhook を削除します。
- Deactivate Webhook および Activate Webhook - Webhook を非アクティブ化します。これにより、Webhook がトリガーされたときにペイロードの配信が停止されます。Webhook が非アクティブ化されている場合、Activate Webhook 操作を使用してペイロードの配信を再開できます。
Notification Status ページには、特定の Webhook に関連付けられたトリガー イベントに関する情報が表示されます。このテーブルを使用することで、Webhook に加え、配信されたペイロードの詳細 (Webhook がトリガーされた時刻、ペイロード URL から受信したレスポンス、配信されたペイロードの内容など) を監視できます。ペイロードの配信が成功したことを示すレコードは、1 日後に削除されます。配信の失敗を示すレコードは 7 日間保存されます。
これらの操作の例については、「Webhooks API」をご参照ください。
詳細パラメーターの構成
詳細パラメーターを使用して、Webhook をさらにカスタマイズできます。これらのパラメーターは、ポータルで構成されているすべての Webhook に適用され、https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/webhooks/settings. からアクセスできます。
Update 操作では、次のパラメーターを更新できます。
- 配信の試行回数 - ペイロードを配信する試行回数を指定します。デフォルトは 3 回ですが、最大 5 回まで増やすことができます。
- 通知タイムアウト - 接続でレスポンスの受信を待機する時間の長さを指定します。この時間内にレスポンスを受信できない場合、接続はタイム アウトし、通知は失敗したと見なされます。
- 配信試行間の経過時間 - 各ペイロード配信試行間の時間を指定します。デフォルトは 30 秒ですが、最大で 100 秒、最小で 1 秒まで増減させることができます。
詳細パラメーターを構成する方法については、「Webhooks API ドキュメント」をご参照ください。
Webhook に関するよくあるご質問 (FAQ)
ArcGIS Enterprise は、組織のファイアウォールの内側にあるオフライン環境に配置されています。この場合でも Webhook を構成できますか？
はい。Webhook を構成するには、ArcGIS Enterprise ポータルから到達可能なペイロード URL を使用する必要があります。このためには、カスタム アプリケーションを構築して内部サーバーに配置します。
アイテム、ユーザー、またはグループの更新を構成するアクションは何ですか？
ポータル アイテム、ユーザー、およびグループの更新を登録している場合、それらのプロパティが更新されるたびに Webhook がトリガーされます。たとえば、ポータル内の特定のアイテムの更新を登録している場合、そのアイテムのタイトル、タグ、またはサムネイルが更新された場合に Webhook がトリガーされます。アクションがポータルの更新を構成しているかどうかを判断する簡単な方法は、ネットワーク トラフィックを調査することです。アクションのたびに [更新] 操作が呼び出される場合、更新を待機している Webhook も同じアクションでトリガーすることができます。
ArcGIS Enterprise ポータルで統合 Windows 認証を使用しています。この場合でも、ポータルへのサイン インおよびサイン アウト (user/<username>/signIn) を登録できますか？
これらのイベントは、ユーザーが OAuth を介してサイン インまたはサイン アウトしたときにのみトリガーされます。このため、統合 Windows 認証 (IWA) および SAML はサポートされていません。ただし、ポータルの組み込みセキュリティおよび PKI はサイン インおよびサイン アウト イベントをサポートしています。
ペイロード URL が停止するか、利用できなくなった場合はどうなりますか？ 配信されなかったペイロードを復元する方法はありますか？
ポータルが到達不能または応答しないペイロード URL または Webhook レシーバーにペイロードを配信する場合、設定済みの [詳細パラメーター] によって再配信の方法とタイミングが決定されます。ペイロードの配信に再度失敗した場合、Webhook の作成時に設定した deactivationPolicy ユーザーに対して 1 件の失敗としてカウントされます。このポリシーに合致すると、Webhook は無効になります。
Webhook の通知ステータスに移動し、試行されたペイロード配信をすべて表示することで、配信が成功したかどうかを判断することができます。