웹 후크 생성 및 관리—Portal for ArcGIS

웹 후크는 한 응용프로그램이 다른 응용프로그램에 이벤트 기반 정보를 제공할 수 있는 메커니즘입니다. ArcGIS Enterprise 포털 관리자는 웹 후크를 생성, 관리, 구성할 수 있습니다. 포털 항목, 그룹, 사용자와 관련된 이벤트가 발생하는 경우 자동으로 알림을 표시하도록 웹 후크를 구성할 수 있습니다. 웹 후크가 트리거되면 고유한 사용자 정의 페이로드 URL에 대한 HTTP 요청이 이루어져 이벤트 관련 정보가 제공됩니다.

주요 용어

다음은 웹 후크의 주요 용어입니다.

트리거 이벤트 - 웹 후크를 트리거하도록 설정한 작업입니다. 예를 들어 기관에서 특정 그룹이 업데이트되거나 항목이 공유될 때 웹 후크가 트리거되도록 구성할 수 있습니다. 웹 후크는 둘 이상의 트리거 이벤트를 포함할 수 있습니다.
페이로드 - 지정된 이벤트가 발생한 후 웹 후크에서 전달된 트리거 이벤트 데이터입니다. 이 정보는 JSON 형식입니다. 자세한 내용은 아래의 페이로드 섹션을 참고하세요.
페이로드 URL - 페이로드가 전송될 위치입니다. 페이로드 URL은 Microsoft Power Automate, Zapier, IFTTT 등의 서비스를 사용하여 생성됩니다. 원하는 플랫폼을 사용하여 사용자 정의 웹서비스 엔드포인트를 생성할 수도 있습니다.

예시 사용 사례

웹 후크를 사용하면 시스템 전체 워크플로를 통합할 수 있으며 기관의 웹 후크를 활용할 수 있는 다양한 방법이 있습니다.

ArcGIS Enterprise에서 활동 모니터링

웹 후크는 ArcGIS Enterprise에서 활동을 모니터링하는 데 사용할 수 있습니다. 예를 들어 특정 항목과 관련된 모든 이벤트에 구독할 수 있습니다. 웹 후크는 항목의 등록정보가 업데이트될 때 트리거되고, HTTPS 요청은 이벤트를 설명하는 데이터가 포함된 페이로드를 전달합니다. 이 페이로드가 전달되는 위치를 결정하고 정보를 받으면 이에 따라 수행할 수 있습니다.

지원되는 트리거 이벤트

웹 후크를 생성할 때 이벤트를 트리거하도록 구독합니다. 이러한 이벤트는 포털 작업이므로 작업의 URI는 웹 후크 구성에 제공되어야 합니다. 아래의 하위 섹션에서는 사용 가능한 트리거 이벤트 및 관련된 URI를 설명합니다.

항목

업데이트할 수 있는 항목 등록정보는 항목 유형에 따라 다르며 /update 작업을 트리거하는 고유한 작업이 있습니다. 예를 들어 항목이 웹 맵인 경우 태그 업데이트, 팝업 구성 또는 베이스맵 변경은 모두 웹 후크를 트리거할 업데이트 이벤트입니다.

다음 테이블에는 웹 맵, 웹 앱, 레이어, 패키지, 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 - 항목 공유 방법(groupID, 기관 또는 모든 사람) 가독성을 위해 형식이 지정된 예시 `//groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }`
특정 항목이 공유 해제됨	/items/<itemID>/unshare	unsharedFromGroups - 항목 공유 해제 방법(groupID, 기관 또는 모든 사람) 가독성을 위해 형식이 지정된 예시 `//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

페이로드

웹 후크가 트리거되면 페이로드가 JSON 형식의 특정 페이로드 URL로 전달됩니다. 각 이벤트는 이벤트와 관련된 정보와 유사한 JSON 스키마를 따릅니다.


키	유형	설명
webhookName	string	페이로드를 전달한 웹 후크의 이름입니다.
webhookId	string	페이로드를 전달한 웹 후크의 ID입니다.
portalURL	string	웹 후크가 등록된 포털의 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	개체	이벤트와 관련된 추가 등록정보입니다. 다음과 같을 수 있습니다. sharedToGroups - 항목 공유 방법(groupID, 기관 또는 모든 사람) unsharedFromGroups - 항목 공유 해제 방법(groupID, 기관 또는 모든 사람) removeUserNames - 그룹에서 제거된 사용자의 사용자 이름 updateUserNames - 그룹 역할이 업데이트된 사용자의 사용자 이름 invitedUserNames - 그룹에 초대된 사용자의 사용자 이름 addedUserNames - 그룹에 추가된 사용자의 사용자 이름 userRoleUpdatedTo - 사용자에게 할당된 새 역할 reassignedTo - 항목이나 그룹이 다시 할당된 새 사용자 userLicenseTypeUpdatedTo - 사용자가 할당된 새 사용자 유형 name - 생성, 업데이트, 삭제된 역할의 이름

페이로드 URL

페이로드 URL은 웹 후크를 만들 때 사용자가 제공해야 합니다. 이를 통해 페이로드가 전달될 위치를 정의합니다. 페이로드는 HTTPS POST 요청을 통해 전달되므로 HTTPS를 통해 통신하고 포털에서 연결할 수 있도록 웹 후크 수신기를 구성해야 합니다. Microsoft Power Automate, Zapier, IFFT 등의 여러 웹서비스를 사용하여 페이로드로 사용자 설정 워크플로를 구성할 수 있습니다. 예를 들어 Microsoft Power Automate에서 페이로드를 수신하면 페이로드를 분석하고 형식을 지정하여 이메일 별칭으로 보내도록 워크플로를 생성할 수 있습니다. 또는 웹서비스를 생성 및 사용자 정의하여 페이로드를 수신할 수 있습니다. 인터넷 접근을 제한하는 기관의 경우 페이로드를 수신할 수 있는 사용자 정의 웹서비스를 생성하는 것을 권장합니다. 즉시 사용 가능한 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": {}
    }
  ]
}

웹 후크 생성

웹 후크는 ArcGIS Portal Directory(API 공유)를 통해서만 관리할 수 있습니다. 웹 후크를 생성하려면 다음 단계를 수행합니다.

ArcGIS Portal Directory로 이동합니다.
https://machine.domain.com/webadaptor/sharing/rest
관리자로 로그인합니다.
웹 후크는 관리자만 생성 및 관리할 수 있습니다.
관리자 사용자 페이지가 나타납니다.
기관 ID 하이퍼링크를 클릭하거나 아래 양식을 요청하여 Portal Self 리소스 페이지로 이동합니다.
https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
페이지 아래쪽으로 스크롤하여 하위 리소스의 Webhooks로 이동합니다.
https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
지원되는 작업에서 Create Webhook를 선택합니다.
웹 후크의 매개변수를 지정합니다.
이러한 매개변수에 대한 자세한 내용은 웹 후크 REST API 설명서를 참고하세요.
이제 내 웹 후크가 웹 후크(https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks) 아래에 나열됩니다.

웹 후크 관리

다음 양식을 요청하여 ArcGIS Portal Directory를 통해 웹 후크를 관리할 수 있습니다.

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.

웹 후크 관리에 지원되는 작업은 다음과 같습니다.

Update Webhook - 웹 후크의 매개변수를 업데이트합니다. 지정된 웹 후크의 이름, 페이로드 URL, 구성 또는 트리거 이벤트를 업데이트할 수 있습니다.
Delete Webhook - 포털에서 웹 후크를 제거합니다.
Deactivate Webhook 및 Activate Webhook - 웹 후크를 비활성화하면 웹 후크가 트리거될 때 페이로드가 전달되지 않습니다. 웹 후크가 비활성화되면 웹 후크 활성화 작업을 통해 페이로드 전달을 재개할 수 있습니다.

Notification Status 페이지는 특정 웹 후크와 연관된 트리거 이벤트의 관련 정보를 표시합니다. 이 테이블을 사용하여 웹 후크뿐 아니라 웹 후크가 트리거된 시간, 페이로드 URL 및 전달된 페이로드에서 수신된 응답과 같이 전달된 페이로드의 세부정보를 모니터링할 수 있습니다. 페이로드가 성공적으로 전달되었음을 나타내는 레코드는 하루가 지나면 제거됩니다. 실패한 전달 시도를 나타내는 레코드는 7일 동안 저장됩니다.

이러한 작업의 예시는 웹 후크 API를 참고하세요.

고급 매개변수 구성

웹 후크를 추가로 사용자 정의하는 데 사용할 수 있는 몇 가지 고급 매개 변수가 있습니다. 이러한 매개변수는 포털에 구성된 모든 웹 후크에 적용되며 https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.에서 접근할 수 있습니다.

Update 작업을 통해 다음 매개변수를 업데이트할 수 있습니다.

전달 시도 횟수 - 페이로드를 전달하기 위한 시도 횟수를 지정합니다. 기본값은 3회 시도이며 5회까지 늘릴 수 있습니다.
알림 시간 제한 - 응답을 수신하기 위해 대기할 연결의 시간 길이를 지정합니다. 이 간격 내에 응답을 받지 못하면 연결 시간이 초과되어 실패한 알림 시도로 간주됩니다.
전달 시도 간의 경과 시간 - 각 페이로드 전달 시도 사이의 시간을 지정합니다. 기본값은 30초이며, 최대 100초로 늘리거나 최소 1초로 줄일 수 있습니다.

고급 매개변수를 구성하는 방법에 대한 자세한 내용은 웹 후크 API 설명서를 참고하세요.

이 항목에 대한 피드백을 제공하시겠습니까?