웹후크는 한 응용프로그램이 다른 응용프로그램에 이벤트 기반 정보를 제공할 수 있는 메커니즘입니다. 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 |
특정 항목이 공유 해제됨 | /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/singOut |
사용자가 삭제됨 | /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 |
페이로드
웹후크가 트리거되면 페이로드가 JSON 형식의 특정 페이로드 URL로 전달됩니다. 각 이벤트는 이벤트와 관련된 정보와 유사한 JSON 스키마를 따릅니다.
| 키 | 유형 | 설명 |
|---|---|---|
| webhookName | 문자열 | 페이로드를 전달한 웹후크의 이름입니다. |
| webhookId | 문자열 | 페이로드를 전달한 웹후크의 ID입니다. |
| portalURL | 문자열 | 웹후크가 등록된 포털의 URL입니다. |
| when | 타임스탬프 | 페이로드가 전달된 시간입니다. |
| username | 문자열 | 이벤트를 트리거한 사용자입니다. |
| userId | 문자열 | 이벤트를 트리거한 사용자의 ID입니다. |
| when | 타임스탬프 | 이벤트가 발생한 시간입니다. |
| operation | 문자열 | 사용자가 수행한 작업입니다. 이는 다음과 같을 수 있습니다.
|
| source | 문자열 | 작업이 수행된 항목 유형입니다. item, group 또는user일 수 있습니다. |
| id | 문자열 | 작업이 수행된 원본 항목의 ID입니다. |
| properties | 객체 | 이벤트와 관련된 추가 등록정보입니다. 이는 다음과 같을 수 있습니다.
|
페이로드 URL
페이로드 URL은 웹후크를 만들 때 사용자가 제공해야 합니다. 이를 통해 페이로드가 전달될 위치를 정의합니다. 페이로드는 HTTPS POST 요청을 통해 전달되므로 HTTPS를 통해 통신하고 포털에서 연결할 수 있도록 웹후크 수신기를 구성해야 합니다. Microsoft Power Automate, Zapier, IFFT 등의 여러 웹서비스를 사용하여 페이로드로 사용자 정의 워크플로를 구성할 수 있습니다. 예를 들어 Microsoft Power Automate에서 페이로드를 수신하면 페이로드를 분석하고 형식을 지정하여 이메일 별칭으로 보내도록 워크플로를 생성할 수 있습니다. 또는 웹서비스를 생성 및 사용자 정의하여 페이로드를 수신할 수 있습니다. 인터넷 접근을 제한하는 기관의 경우 페이로드를 수신할 수 있는 사용자 정의 웹서비스를 생성하는 것을 권장합니다. 즉시 사용 가능한 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": {}
}]
}
웹후크 생성
웹후크는 ArcGIS Portal Directory를 통해서만 관리할 수 있습니다. 웹후크를 생성하려면 다음 단계를 수행합니다.
- ArcGIS Portal Directory로 이동합니다.https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- 관리자로 로그인합니다.
웹후크는 관리자만 생성 및 관리할 수 있습니다.
관리자 사용자 페이지가 나타납니다.
- 기관 ID 하이퍼링크를 클릭하거나 아래 양식을 요청하여 Portal Self 리소스 페이지로 이동합니다.https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- 페이지 아래쪽으로 스크롤하여 하위 리소스의 Webhooks로 이동합니다.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
- 지원되는 작업에서 Create Webhook를 선택합니다.
- 웹후크의 매개변수를 지정합니다.
이러한 매개변수에 대한 자세한 내용은 웹후크 REST API 설명서를 참고하세요.
내 웹후크가 웹후크 아래에 나열됩니다. https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
웹후크 관리
다음 양식을 요청하여 ArcGIS Portal Directory를 통해 웹후크를 관리할 수 있습니다.
(https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>)
웹후크 관리에 지원되는 작업은 다음과 같습니다.
- Update Webhook - 웹후크의 매개변수를 업데이트합니다. 지정된 웹후크의 이름, 페이로드 URL, 구성 또는 트리거 이벤트를 업데이트할 수 있습니다.
- Delete Webhook - 포털에서 웹후크를 제거합니다.
- Deactivate Webhook 및 Activate Webhook - 웹후크를 비활성화하면 웹후크가 트리거될 때 페이로드가 전달되지 않습니다. 웹후크가 비활성화되면 웹후크 활성화 작업을 통해 페이로드 전달을 재개할 수 있습니다.
Notification Status 페이지는 특정 웹후크와 연관된 트리거 이벤트의 관련 정보를 표시합니다. 이 테이블을 사용하여 웹후크뿐 아니라 웹후크가 트리거된 시간, 페이로드 URL 및 전달된 페이로드에서 수신된 응답과 같이 전달된 페이로드의 세부정보를 모니터링할 수 있습니다. 페이로드가 성공적으로 전달되었음을 나타내는 레코드는 하루가 지나면 제거됩니다. 실패한 전달 시도를 나타내는 레코드는 7일 동안 저장됩니다.
이러한 작업의 예시는 웹후크 API를 참고하세요.
고급 매개변수 구성
웹후크를 추가로 사용자 정의하는 데 사용할 수 있는 몇 가지 고급 매개 변수가 있습니다. 이러한 매개변수는 포털에 구성된 모든 웹후크에 적용되며 https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/webhooks/settings.에서 접근할 수 있습니다.
Update 작업을 통해 다음 매개변수를 업데이트할 수 있습니다.
- 전달 시도 횟수 - 페이로드를 전달하기 위한 시도 횟수를 지정합니다. 기본값은 3회 시도이며 5회까지 늘릴 수 있습니다.
- 알림 시간 제한 - 응답을 수신하기 위해 대기할 연결의 시간 길이를 지정합니다. 이 간격 내에 응답을 받지 못하면 연결 시간이 초과되어 실패한 알림 시도로 간주됩니다.
- 전달 시도 간의 경과 시간 - 각 페이로드 전달 시도 사이의 시간을 지정합니다. 기본값은 30초이며, 최대 100초로 늘리거나 최소 1초로 줄일 수 있습니다.
고급 매개변수를 구성하는 방법에 대한 자세한 내용은 웹후크 API 설명서를 참고하세요.
웹후크 자주 묻는 질문
My ArcGIS Enterprise가 기관의 방화벽으로 보호되는 오프라인 환경에 배포됩니다. 웹후크를 계속 구성할 수 있나요?
예, 웹후크를 구성하려면 ArcGIS Enterprise Portal에서 연결할 수 있는 페이로드 URL을 사용해야 합니다. 이 작업을 수행하려면 사용자 정의 응용프로그램을 생성한 후 내부 서버에 배포하면 됩니다.
어떤 항목, 사용자, 그룹에 대한 업데이트를 구성하나요?
포털 항목, 사용자, 그룹에 대한 업데이트를 구독한 경우 등록정보가 업데이트될 때마다 웹후크가 트리거됩니다. 예를 들어 포털의 특정 항목에 대한 업데이트를 구독한 경우 해당 항목의 제목, 태그, 썸네일 이미지가 업데이트되면 웹후크가 트리거됩니다. 작업이 포털에서 업데이트를 구성하는지 여부를 쉽게 판단할 수 있는 방법은 네트워크 트래픽을 확인하는 것입니다. 작업의 결과로 업데이트 작업이 호출될 때마다 동일한 작업을 통해 업데이트를 수신하는 웹후크를 트리거할 수도 있습니다.
ArcGIS Enterprise Portal에서 Windows 통합 인증을 사용하고 있습니다. 사용자의 포털(user/<username>/signIn) 로그인과 로그아웃을 계속 구독할 수 있나요?
이러한 이벤트는 사용자가 OAuth를 통해 로그인하거나 로그아웃할 때만 트리거됩니다. 따라서 Windows 통합 인증(IWA)과 SAML은 지원되지 않습니다. 단, 포털의 빌트인 보안과 PKI에는 로그인 및 로그아웃 이벤트가 지원됩니다.
페이로드 URL이 다운되거나 사용할 수 없게 되면 어떻게 되나요? 전달되지 않은 페이로드를 복구할 수 있는 방법이 있나요?
포털이 연결할 수 없거나 응답하지 않는 페이로드 URL 또는 웹후크 수신기에 페이로드 전달을 시도하면 설정한 고급 매개변수에 따라 포털에서 다른 전달을 시도하는 방법과 시기가 결정됩니다. 이러한 추가 시도에도 페이로드 전달이 실패하면 웹후크를 생성할 때 설정한 deactivationPolicy에 대해 실패로 간주됩니다. 이 정책이 충족되면 웹후크가 비활성화됩니다.
웹후크의 알림 상태로 이동하여 시도한 모든 페이로드 전달을 보고 해당 페이로드가 성공적으로 전달되었는지 여부를 확인할 수 있습니다.