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/delete |
任意のアイテムが更新された | /items/update |
任意のアイテムが移動されたか、その所有権が変更された | /items/move |
任意のアイテムが公開された | /items/publish |
任意のアイテムが共有された | /items/share |
任意のアイテムの共有が解除された | /items/unshare |
任意のアイテムの所有権が再割り当てされた | /items/reassign |
特定のアイテムに対するすべてのトリガー イベント | /items/<itemID> |
特定のアイテムが削除された | /items/<itemID>/delete |
特定のアイテムのプロパティが更新された | /items/<itemID>/update |
特定のアイテムの所有権が変更されたか、アイテムが移動された | /items/<itemID>/move |
特定のアイテムが公開された | /items/<itemID>/publish |
特定のアイテムが共有された | /items/<itemID>/share |
特定のアイテムの共有が解除された | /items/<itemID>/unshare |
特定のアイテムの所有権が再割り当てされた | /items/<itemID>/reassign |
グループ
グループ設定に対する一般的な変更はすべて更新として扱われます。 たとえば、グループのアクセス権限を変更すると更新イベントが発生します。
次の表に、グループに関連付けられているトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
全グループに対するすべてのトリガー イベント | /groups |
グループが追加された | /groups/add |
任意のグループが更新された | /groups/update |
任意のグループが削除された | /groups/delete |
任意のグループに対して [削除の防止] が有効化された | /groups/protect |
任意のグループに対して [削除の防止] が無効化された | /groups/unprotect |
ユーザーが任意のグループに招待された | /groups/invite |
ユーザーが任意のグループに追加された | /groups/addUsers |
ユーザーが任意のグループから削除された | /groups/removeUsers |
ユーザーのロールが任意のグループで更新された | /groups/updateUsers |
任意のグループの所有権が再割り当てされた | /groups/reassign |
特定のグループに対するすべてのトリガー イベント | /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 |
特定のグループの所有権が再割り当てされた | /groups/<groupID>/reassign |
ユーザー
更新イベントは、ユーザー プロファイルが変更されるたびにトリガーされます。 ただし、ユーザー ロール、ユーザー タイプ、またはライセンスに加えられた変更は、ユーザー プロファイルの更新とは見なされません。
次の表に、ユーザーに関連付けられているトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
ポータル内の全ユーザーに対するすべてのトリガー イベント | /users |
ユーザーが組織に追加された | /users/add |
任意のユーザーがポータルにサイン インした | /users/signin |
任意のユーザーがポータルからサイン アウトした | /users/signout |
任意のユーザーが削除された | /users/delete |
任意のユーザーのプロファイルが更新された | /users/update |
任意のユーザーのアカウントが無効化された | /users/disable |
任意のユーザーのアカウントが有効化された | /users/enable |
任意のユーザーに新しいロールが割り当てられた | /users/updateUserRole |
任意のユーザーに新しいユーザー タイプが割り当てられた | /users/updateUserLicenseType |
特定のユーザーに関連付けられているすべてのトリガー イベント | /users/<username> |
特定のユーザーがポータルにサイン インした | /users/<username>/signIn |
特定のユーザーがポータルからサイン アウトした | /users/<username>/signOut |
特定のユーザーが削除された | /users/<username>/delete |
特定のユーザーのプロファイルが更新された | /users/<username>/update |
特定のユーザーのアカウントが無効化された | /users/<username>/disable |
特定のユーザーのアカウントが有効化された | /users/<username>/enable |
特定のユーザーに新しいロールが割り当てられた | /users/<username>/updateUserRole |
特定のユーザーに新しいユーザー タイプが割り当てられた | /users/<username>/updateUserLicenseType |
ロール
更新イベントは、組織のロールが変更されるたびにトリガーされます。
次の表に、ユーザー ロールに関連付けられているトリガー イベントを示します。
| トリガー イベント | URI の例 |
|---|---|
ポータル内の全ロールに対するすべてのトリガー イベント | /roles |
新しいロールが作成された | /roles/add |
既存のロールが更新された | /roles/updated |
既存のロールが削除された | /roles/delete |
ペイロード
Webhook がトリガーされると、ペイロードが JSON 形式で特定のペイロード URL に配信されます。 各イベントは、そのイベントに関連する情報を含む同様の JSON スキーマに従います。
| キー | タイプ | 説明 |
|---|---|---|
| webhookName | string | ペイロードを配信した Webhook の名前。 |
| webhookId | string | ペイロードを配信した Webhook の ID。 |
| portalURL | string | Webhook が登録されているポータルの URL。 |
| when | timestamp | ペイロードが配信された時刻。 |
| username | string | イベントをトリガーしたユーザー。 |
| userId | string | イベントをトリガーしたユーザーの ID。 |
| when | timestamp | イベントが発生した時刻。 |
| operation | string | ユーザーが実行した操作。 次の値を指定できます。
|
| source | string | 操作が実行されたアイテム タイプ。 item、group、または user のいずれかです。 |
| id | string | 操作が実行されたソース アイテムの ID。 |
| properties | object | イベントに関連付けられているその他のプロパティ。 次の値を指定できます。
|
ペイロード 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://orgURL/portal/",
"when": 1543192196521
},
"events": [{
"username": "administrator",
"userId": "173dd04b69134bdf99c5000aad0b6298",
"when": 1543192196521,
"operation": "update",
"source": "group",
"id": "173dd04b69134bdf99c5000aad0b6298",
"properties": {}
}]
}
Webhook の作成
Webhook は、ArcGIS Portal Directory (共有 API) を介してのみ管理できます。 Webhook を作成するには、次の手順に従います。
- ArcGIS Portal Directory に移動します。https://machine.domain.com/webadaptor/sharing/rest
- 管理者としてサイン インします。
Webhook は管理者のみが作成および管理できます。
管理者ユーザー ページが表示されます。
- [Org ID] ハイパーリンクをクリックするか、以下のフォームのリクエストを行い、[Portal] → [Self] リソース ページに移動します。https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
- ページの下部にスクロールし、[Child Resources] の下にある Webhooks に移動します。https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
- [Supported Operation] で、Create Webhook を選択します。
- Webhook のパラメーターを指定します。
これらのパラメーターの詳細については、Webhook の REST API ドキュメントをご参照ください。
作成した Webhook は、他の Webhook の下に表示されます (https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks)。
Webhook の管理
次のフォームでリクエストを送信することで、ArcGIS Portal Directory を通じて Webhook を管理できます。
https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<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://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings. からアクセスできます。
Update 操作では、次のパラメーターを更新できます。
- 配信の試行回数 - ペイロードを配信する試行回数を指定します。 デフォルトは 3 回ですが、最大 5 回まで増やすことができます。
- 通知タイムアウト - 接続でレスポンスの受信を待機する時間の長さを指定します。 この時間内にレスポンスを受信できない場合、接続はタイム アウトし、通知は失敗したと見なされます。
- 配信試行間の経過時間 - 各ペイロード配信試行間の時間を指定します。 デフォルトは 30 秒ですが、最大で 100 秒、最小で 1 秒まで増減させることができます。
詳細パラメーターを構成する方法については、「Webhooks API ドキュメント」をご参照ください。
Webhook に関するよくあるご質問 (FAQ)
Webhook を使用する際のよくある質問は以下のとおりです。
ArcGIS Enterprise は、組織のファイアウォールの内側にあるオフライン環境にデプロイされています。 この場合でも Webhook を構成できますか？
はい。 Webhook を構成するには、ArcGIS Enterprise ポータルから到達可能なペイロード URL を使用する必要があります。 このためには、カスタム アプリケーションを構築して内部サーバーにデプロイします。
アイテム、ユーザー、またはグループの更新を構成するアクションは何ですか？
ポータル アイテム、ユーザー、およびグループの更新を登録している場合、それらのプロパティが更新されるたびに Webhook がトリガーされます。 たとえば、ポータル内の特定のアイテムの更新を登録している場合、そのアイテムのタイトル、タグ、またはサムネイルが更新された場合に Webhook がトリガーされます。 アクションがポータルの更新を構成しているかどうかを判断する方法の 1 つは、ネットワーク トラフィックを調査することです。 アクションのたびに [更新] 操作が呼び出される場合、更新を待機している Webhook も同じアクションでトリガーすることができます。
ArcGIS Enterprise ポータルで統合 Windows 認証を使用しています。 この場合でも、ポータルへのサイン インおよびサイン アウト (user/<username>/signIn) を登録できますか？
10.9 以降、/signin トリガー イベントを使用して、ポータル認証、Web 層認証、およびエンタープライズ ログインのサイン イン イベントをキャプチャできます。
ペイロード URL が停止するか、利用できなくなった場合はどうなりますか？ 配信されなかったペイロードを復元する方法はありますか？
ポータルが到達不能または応答しないペイロード URL または Webhook レシーバーにペイロードを配信する場合、設定済みの [詳細パラメーター] によって再配信の方法とタイミングが決定されます。 ペイロードの送信に再度失敗した場合、Webhook の作成時に設定した deactivationPolicy ユーザーに対して 1 件の失敗としてカウントされます。 このポリシーに合致すると、Webhook は無効になります。
Webhook の通知ステータスに移動し、試行されたペイロード配信をすべて表示することで、配信が成功したかどうかを判断することができます。