トップへ戻る

Webhook の作成と管理

このトピックの内容

  1. 主要な用語
  2. 使用例
  3. サポートされているトリガー イベント
  4. ペイロード
  5. ペイロード URL
  6. Webhook の作成
  7. Webhook の管理
  8. 詳細パラメーターの構成

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 を作成するには、次の手順に従います。

  1. ArcGIS Portal Directory に移動します。
    https://organization.domain.com/context/sharing/rest
  2. 管理者としてサイン インします。

    Webhook は管理者のみが作成および管理できます。

    管理者ユーザー ページが表示されます。

  3. [Org ID] ハイパーリンクをクリックするか、以下のフォームのリクエストを行い、[Portal] → [Self] リソース ページに移動します。
    https://organization.domain.com/context/sharing/rest/portals/<orgID>
  4. ページの下部にスクロールし、[Child Resources] の下にある Webhooks に移動します。
    https://organization.domain/com/context/sharing/rest/portals/<orgID>/webhooks
  5. [Supported Operation] で、Create Webhook を選択します。
  6. Webhook のパラメーターを指定します。

    これらのパラメーターの詳細については、Webhook の REST API ドキュメントをご参照ください。

    作成した Webhook は、他の Webhook の下に表示されます: https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks。

Webhook の管理

次のフォームでリクエストを送信することで、ArcGIS Portal Directory を通じて Webhook を管理できます。

https://organization.domain.com/context/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://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks/settings. からアクセスできます。

Update 操作では、次のパラメーターを更新できます。

  • 配信の試行回数 - ペイロードを配信する試行回数を指定します。 デフォルトは 3 回ですが、最大 5 回まで増やすことができます。
  • 通知タイムアウト - 接続でレスポンスの受信を待機する時間の長さを指定します。 この時間内にレスポンスを受信できない場合、接続はタイム アウトし、通知は失敗したと見なされます。
  • 配信試行間の経過時間 - 各ペイロード配信試行間の時間を指定します。 デフォルトは 30 秒ですが、最大で 100 秒、最小で 1 秒まで増減させることができます。

詳細パラメーターを構成する方法については、「Webhooks API ドキュメント」をご参照ください。

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

このトピックの内容
  1. 主要な用語
  2. 使用例
  3. サポートされているトリガー イベント
  4. ペイロード
  5. ペイロード URL
  6. Webhook の作成
  7. Webhook の管理
  8. 詳細パラメーターの構成