Azure Web PubSub 서비스의 이벤트 처리기

아티클
03/15/2024

이벤트 처리기는 수신 클라이언트 이벤트를 처리합니다. 이벤트 처리기는 Azure Portal 또는 Azure CLI를 통해 서비스에 등록 및 구성됩니다. 클라이언트 이벤트가 트리거되면 서비스는 적절한 이벤트 처리기에 이벤트를 보낼 수 있습니다. Web PubSub 서비스는 이제 이벤트 처리기를 서버 쪽으로 지원하여 이벤트가 트리거될 때 호출할 서비스에 대한 공용 액세스 가능 엔드포인트를 노출합니다. 즉, 웹후크 역할을 합니다.

Web PubSub 서비스는 CloudEvents HTTP 프로토콜을 사용하여 클라이언트 이벤트를 업스트림 웹후크에 전달합니다.

모든 이벤트에 대해 서비스는 등록된 업스트림 엔드포인트에 대한 HTTP POST 요청을 수식화하고 HTTP 응답을 기대합니다.

서비스에서 서버로 보내는 데이터는 항상 CloudEvents binary 형식입니다.

Screenshot of Web PubSub service event trigger.

업스트림 및 유효성 검사

웹후크 엔드포인트를 구성할 때 URL에서 {event} 매개 변수를 사용하여 URL 템플릿을 정의할 수 있습니다. 서비스는 클라이언트 요청이 들어올 때 웹후크 URL의 값을 동적으로 계산합니다. 예를 들어 허브 chat에 맞게 구성된 이벤트 처리기 URL 패턴 http://host.com/api/{event}와 함께 요청 /client/hubs/chat가 들어오면 클라이언트가 연결할 때 먼저 이 URL http://host.com/api/connect에 POST합니다. {event} 매개 변수는 PubSub WebSocket 클라이언트가 사용자 지정 이벤트를 보낼 때 유용할 수 있습니다. 즉, 이벤트 처리기가 다른 이벤트를 다른 업스트림 엔드포인트로 전달하는 데 도움이 됩니다. {event} 매개 변수는 URL 도메인 이름에서 허용되지 않습니다.

Azure Portal 또는 CLI를 통해 이벤트 처리기 웹후크를 설정할 때 서비스는 CloudEvents 남용 방지를 따라 업스트림 웹후크의 유효성을 검사합니다. 등록된 모든 업스트림 웹후크 URL은 이 메커니즘에 의해 유효성이 검사됩니다. WebHook-Request-Origin 요청 헤더가 서비스 도메인 이름 xxx.webpubsub.azure.com으로 설정되었으며 응답에 이 도메인 이름 또는 *를 포함하는 헤더 WebHook-Allowed-Origin이 있을 것으로 예상합니다.

유효성 검사를 수행할 때 {event} 매개 변수는 validate로 확인됩니다. 예를 들어, URL을 http://host.com/api/{event}로 설정하려고 할 때 서비스는 http://host.com/api/validate에 대한 요청을 OPTIONS하려고 시도합니다. 응답이 유효한 경우에만 구성을 성공적으로 설정할 수 있습니다.

현재로서는 WebHook-Request-Rate 및 WebHook-Request-Callback을 지원하지 않습니다.

서비스와 웹후크 간 인증

이러한 메서드를 사용하여 서비스와 웹후크 간을 인증할 수 있습니다.

익명 모드
쿼리 매개 변수로 구성된 Webhook URL을 통해 ?code=<code>로 단순 인증을 제공합니다.
Microsoft Entra 권한 부여 자세한 내용은 클라이언트 이벤트에서 관리 ID 사용을 참조하세요.

이벤트 처리기 구성

Azure Portal을 통해 구성

새 허브에 이벤트 처리기를 추가하거나 기존 허브를 편집할 수 있습니다.

새 허브에서 이벤트 처리기를 구성하려면 다음을 수행합니다.

Azure Portal의 Azure Web PubSub 서비스 페이지로 이동합니다.
메뉴에서 설정을 선택합니다.
추가를 선택하여 허브를 만들고 서버 쪽 웹후크 URL을 구성합니다. 참고: 기존 허브에 이벤트 처리기를 추가하려면 허브를 선택하고 편집을 선택합니다.
허브 이름을 입력합니다.
이벤트 처리기 구성에서 추가를 선택합니다.
이벤트 처리기 페이지에서 다음 필드를 구성합니다. 1. URL 템플릿 필드에 서버 웹후크 URL을 입력합니다. 1. 구독하려는 시스템 이벤트를 선택합니다. 1. 구독하려는 사용자 이벤트를 선택합니다. 1. 인증 방법을 선택하여 업스트림 요청을 인증합니다. 1. 확인을 선택합니다.
허브 설정 구성 페이지의 맨 위에 있는 저장을 선택합니다.

Azure CLI를 통해 구성

Azure CLI az webpubsub hub 그룹 명령을 사용하여 이벤트 처리기 설정을 구성합니다.

명령	설명
`create`	WebPubSub 서비스에 대한 허브 설정을 만듭니다.
`delete`	WebPubSub 서비스에 대한 허브 설정을 삭제합니다.
`list`	WebPubSub 서비스에 대한 모든 허브 설정을 나열합니다.
`show`	WebPubSub 서비스에 대한 허브 설정을 표시합니다.
`update`	WebPubSub 서비스에 대한 허브 설정을 업데이트합니다.

다음은 MyWebPubSub 리소스의 허브 MyHub에 대해 2개의 웹후크 URL을 만드는 예입니다.

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"