Azure Web PubSub 서비스에서 이벤트 처리기 구성

아티클
08/07/2024

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

Web PubSub 서비스는 CloudEvents HTTP 프로토콜을 사용하여 구성된 업스트림 웹후크에 클라이언트 이벤트를 제공하고 Azure Web PubSub 이벤트 처리기에 대한 CloudEvents 확장을 제공합니다.

Web PubSub 서비스 이벤트 트리거의 스크린샷.

이벤트 처리기 설정

클라이언트는 항상 허브에 연결되며 허브에 대한 여러 이벤트 처리기 설정을 구성할 수 있습니다. 이벤트 처리기 설정 순서는 중요하며 이전 설정의 우선 순위가 더 높습니다. 클라이언트가 연결되고 이벤트가 트리거되면 Web PubSub는 구성된 이벤트 처리기를 우선 순위 순서로 통과하고 일치하는 첫 번째 이벤트 처리기가 우선합니다. 이벤트 처리기를 구성할 때 아래 속성을 설정해야 합니다.

Property name	설명
URL 템플릿	Web PubSub에서 업스트림 웹후크 URL을 평가하는 데 사용하는 템플릿을 정의합니다.
사용자 이벤트	현재 이벤트 처리기 설정에서 관심 있는 사용자 이벤트를 정의합니다.
시스템 이벤트	현재 이벤트 처리기 설정에서 관심 있는 시스템 이벤트를 정의합니다.
인증	Web PubSub 서비스와 업스트림 서버 간의 인증 방법을 정의합니다.

이벤트

이벤트에는 사용자 이벤트와 시스템 이벤트가 포함됩니다. 시스템 이벤트는 클라이언트의 수명 동안 트리거되는 미리 정의된 이벤트이며, 사용자 이벤트는 클라이언트가 데이터를 전송할 때 트리거되는 이벤트이며, 클라이언트 프로토콜을 사용하여 사용자 이벤트 이름을 사용자 지정할 수 있습니다. 여기에 자세한 설명이 포함되어 있습니다.

이벤트 유형	지원되는 값
시스템 이벤트	`connect`, `connected`및 `disconnected`
사용자 이벤트	`message`, 또는 클라이언트 프로토콜을 따르는 사용자 지정 이벤트 이름

URL 템플릿

URL 템플릿은 런타임 중에 평가할 수 있는 여러 매개 변수를 지원합니다. 이 기능을 사용하면 단일 설정으로 다른 허브 또는 이벤트를 다른 업스트림 서버로 쉽게 라우팅할 수 있습니다. 데이터를 Azure Key Vault에 안전하게 저장할 수 있도록 KeyVault 참조 구문도 지원됩니다.

참고 URL 도메인 이름에는 매개 변수 구문이 포함되어서는 안 됩니다(예: http://{hub}.com은 유효한 URL 템플릿이 아닙니다).

지원되는 매개 변수	구문	설명	샘플
허브 매개 변수	`{hub}`	값은 클라이언트가 연결하는 허브입니다.	클라이언트가 연결되면 `client/hubs/chat`URL 템플릿`http://host.com/api/{hub}`은 `http://host.com/api/chat`이 클라이언트의 경우 허브`chat`가 되므로 평가됩니다.
이벤트 매개 변수	`{event}`	트리거된 이벤트의 값입니다. `event` 값은 여기에 나열됩니다. 남용 방지 요청에 대한 이벤트 값은 `validate` 여기에 설명되어 있습니다.	이벤트에 대해 구성된 URL 템플릿`http://host.com/api/{hub}/{event}`이 있는 경우 `connect`클라이언트가 연결할 `client/hubs/chat`때 Web PubSub는 클라이언트가 연결될 때 평가된 URL`http://host.com/api/chat/connect`에 대한 POST 요청을 시작합니다. 이 클라이언트 이벤트의 경우 허브가 `chat`이 이벤트 처리기 설정을 트리거하는 이벤트이기 때문입니다`connect`.
KeyVault 참조 매개 변수	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri는 자격 증명 모음에 있는 비밀의 전체 데이터 평면 URI여야 하며, 선택적으로 버전(예: `https://myvault.vault.azure.net/secrets/mysecret/` 또는 `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`)을 포함해야 합니다. KeyVault 참조를 사용하는 경우 Web PubSub 서비스와 KeyVault 서비스 간에 인증을 구성해야 합니다. 자세한 단계는 여기를 참조하세요.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

서비스와 웹후크 간 인증

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

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

업스트림 및 유효성 검사

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을 지원하지 않습니다.

이벤트 처리기 구성

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"