Webhook の作成と管理—Portal for ArcGIS | ArcGIS Enterprise のドキュメント

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	sharedToGroups - アイテムの共有方法 (グループ ID、組織、またはすべてのユーザー) 読みやすいように書式設定されている例 `//groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }`
特定のアイテムの共有が解除された	/items/<itemID>/unshare	unsharedFromGroups - アイテムの共有解除方法 (グループ ID、組織、またはすべてのユーザー) 読みやすいように書式設定されている例 `//Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }`
特定のアイテムの所有権が再割り当てされた	/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	invitedUserNames - グループに招待されたユーザーのユーザー名読みやすいように書式設定されている例 `"properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }`
ユーザーが特定のグループに追加された	/groups/<groupID>/addUsers	addedUserNames - グループに追加されたユーザーのユーザー名。読みやすいように書式設定されている例 `"properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }`
ユーザーが特定のグループから削除された	/groups/<groupID>/removeUsers	- removeUserNames - グループから削除されたユーザーのユーザー名。読みやすいように書式設定されている例 `"properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }`
ユーザーのロールが特定のグループで更新された	/groups/<groupID>/updateUsers	updateUserNames - グループのロールが更新されたユーザーのユーザー名。読みやすいように書式設定されている例 `"properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }`
特定のグループの所有権が再割り当てされた	/groups/<groupID>/reassign
アイテムが、グループに共有されます。	/groups/<groupID>/itemShare	sharedItems - グループに共有されているアイテムの itemID とアイテムタイプ。読みやすいように書式設定されている例 `"properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }`
アイテムは特定のグループから共有されていません。	/groups/<groupID>/itemUnshare	unsharedItems - グループから共有されていないアイテムの itemID とアイテムタイプ。読みやすいように書式設定されている例 `"properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }`

ユーザー

更新イベントは、ユーザープロファイルが変更されるたびにトリガーされます。ただし、ユーザーロール、ユーザータイプ、またはライセンスに加えられた変更は、ユーザープロファイルの更新とは見なされません。

次の表に、ユーザーに関連付けられているトリガーイベントを示します。


トリガーイベント	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	userRoleUpdatedTo - ユーザーが割り当てられた新しいロール。読みやすいように書式設定されている例 `"properties": { "userRoleUpdatedTo": ["New role"] }`
特定のユーザーに新しいユーザータイプが割り当てられた	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo - ユーザーが割り当てられた新しいユーザータイプ。読みやすいように書式設定されている例 `"properties": { "userLicenseTypeUpdatedTo": ["Editor"] }`

ロール

更新イベントは、組織のロールが変更されるたびにトリガーされます。

次の表に、ユーザーロールに関連付けられているトリガーイベントを示します。


トリガーイベント	URI の例	プロパティ
ポータル内の全ロールに対するすべてのトリガーイベント	/roles
新しいロールが作成された	/roles/add	name - 作成、更新、または削除されたロールの名前。読みやすいように書式設定されている例 `"properties": { "name": ["New role"] }`
既存のロールが更新された	/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	ユーザーが実行した操作。次の値を指定できます。 add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
source	string	操作が実行されたアイテムタイプ。 item、group、または user のいずれかです。
id	string	操作が実行されたソースアイテムの ID。
properties	object	イベントに関連付けられているその他のプロパティ。次の値を指定できます。 sharedToGroups - アイテムの共有方法 (グループ ID、組織、またはすべてのユーザー) unsharedFromGroups - アイテムの共有解除方法 (グループ ID、組織、またはすべてのユーザー) removeUserNames - グループから削除されたユーザーのユーザー名 updateUserNames - グループのロールが更新されたユーザーのユーザー名。 invitedUserNames - グループに招待されたユーザーのユーザー名 addedUserNames - グループに追加されたユーザーのユーザー名 userRoleUpdatedTo - ユーザーが割り当てられた新しいロール reassignedTo - アイテムまたはグループが再割り当てされた新しいユーザー userLicenseTypeUpdatedTo - ユーザーが割り当てられた新しいユーザータイプ name - 作成、更新、または削除されたロールの名前

ペイロード 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 ドキュメント」をご参照ください。

このトピックへのフィードバック