HTTP 프로토콜을 사용하는 Azure Web PubSub 이벤트 처리기용 CloudEvents 확장

아티클
03/13/2024

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

Web PubSub 서비스에서 서버로 전송되는 데이터는 항상 CloudEvents binary 형식입니다.

웹후크 유효성 검사
Web PubSub CloudEvents 특성 확장
이벤트
- 차단 이벤트
  - 시스템 connect 이벤트
  - 사용자 이벤트
- 이벤트 차단 해제
  - 시스템 connected 이벤트
  - 시스템 disconnected 이벤트

웹후크 유효성 검사

웹후크 유효성 검사는 CloudEvents를 따릅니다. 요청은 항상 헤더에 포함됩니다 WebHook-Request-Origin: xxx.webpubsub.azure.com .

배달 대상이 이벤트 배달을 허용하는 경우에만 헤더를 포함하여 WebHook-Allowed-Origin 요청에 회신해야 합니다. 예를 들면 다음과 같습니다.

WebHook-Allowed-Origin: *

또는

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

지금은 WebHook-Request-Rate 및 WebHook-Request-Callback 이 지원되지 않습니다.

Web PubSub CloudEvents 특성 확장

또한 HTTP 사양은 더 이상 확장 HTTP 헤더에 X-접두사를 지정하지 않음으로써 유사한 패턴을 따르고 있다는 점에 주목했습니다.

이 확장은 Web PubSub에서 생성하는 모든 이벤트에 사용되는 특성을 정의합니다.

특성

속성	형식	Description
`userId`	`string`	연결을 인증한 사용자
`hub`	`string`	연결이 속한 허브
`connectionId`	`string`	connectionId는 클라이언트 연결에 고유합니다.
`eventName`	`string`	접두사를 사용하지 않는 이벤트의 이름입니다.
`subprotocol`	`string`	클라이언트가 사용 중인 하위 프로토콜(있는 경우)
`connectionState`	`string`	연결 상태를 정의합니다. 동일한 응답 헤더를 사용하여 상태 값을 초기화할 수 있습니다. 여러 `connectionState` 헤더는 허용되지 않습니다. 예를 들어 `base64(jsonString)` 이 특성을 사용하여 복합 개체를 전달하기 위해 내부에 복합 문자가 포함된 경우 base64에서 문자열 값을 인코딩합니다.
`signature`	`string`	들어오는 요청이 예상 원본에서 온 것인지 유효성을 검사하는 업스트림 웹후크의 서명입니다. 서비스는 기본 액세스 키와 보조 액세스 키를 모두 키`Hex_encoded(HMAC_SHA256(accessKey, connectionId))`로 `HMAC` 사용하여 값을 계산합니다. 업스트림 처리하기 전에 요청이 유효한지 검사 합니다.

이벤트

이벤트 유형에는 두 가지가 있습니다. 하나는 서비스에서 이벤트의 응답이 계속되기를 기다리는 이벤트를 차단하는 것입니다. 하나는 서비스가 다음 메시지를 처리하기 전에 해당 이벤트의 응답을 기다리지 않는 이벤트를 차단 해제하는 것입니다.

차단 이벤트
- 시스템 connect 이벤트
- 사용자 이벤트
이벤트 차단 해제
- 시스템 connected 이벤트
- 시스템 disconnected 이벤트

시스템 `connect` 이벤트

ce-type: azure.webpubsub.sys.connect
Content-Type: application/json

요청 형식:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

성공 응답 형식:

헤더 ce-connectionState: 이 헤더가 있으면 이 연결의 연결 상태가 헤더 값으로 업데이트됩니다. 차단 이벤트만 연결 상태를 업데이트할 수 있습니다. 아래 샘플은 base64로 인코딩된 JSON 문자열을 사용하여 연결에 대한 복잡한 상태를 저장합니다.
상태 코드:
- 204: 성공, 콘텐츠가 없습니다.
- 200: 성공하면 콘텐츠는 JSON 형식이어야 하며 다음 속성이 허용됩니다.
  - subprotocols
    
    이 connect 이벤트는 클라이언트에서 업스트림으로 하위 프로토콜 및 인증 정보를 전달합니다. Web PubSub 서비스는 상태 코드를 사용하여 요청이 WebSocket 프로토콜로 업그레이드되는지 여부를 결정합니다.
    
    요청에 속성이 subprotocols 포함된 경우 서버는 지원하는 하위 프로토콜을 하나 반환해야 합니다. 서버가 하위 프로토콜을 사용하지 않으려는 경우 응답으로 subprotocol 속성을 보내지 않습니다. 빈 헤더를 보낼 수 없습니다.
  - userId: {auth-ed user ID}
    
    서비스가 익명 연결을 허용하므로 서비스에 클라이언트 연결의 사용자 ID를 알려주는 것은 connect 이벤트의 책임입니다. 서비스가 있는 경우 응답 페이로드 userId 에서 사용자 ID를 읽습니다. 요청 클레임이나 이벤트의 응답 페이로드에서 사용자 ID를 읽을 수 없는 경우 연결이 connect 끊깁니다.
  - groups: {groups to join}
    
    이 속성은 사용자가 이 연결을 하나 또는 여러 그룹에 추가할 수 있는 편리한 방법을 제공합니다. 이러한 방식으로 일부 그룹에 이 연결을 추가하기 위해 다른 호출이 필요하지 않습니다.
  - roles: {roles the client has}
    
    이 속성은 업스트림 웹후크가 클라이언트에 권한을 부여하는 방법을 제공합니다. PubSub WebSocket 클라이언트에 대한 초기 권한을 부여하는 다양한 역할이 있습니다. 권한에 대한 자세한 내용은 클라이언트 권한에 설명되어 있습니다.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

오류 응답 형식:

4xx: 오류, 업스트림의 응답이 클라이언트 요청에 대한 응답으로 반환됩니다.

HTTP/1.1 401 Unauthorized

시스템 `connected` 이벤트

클라이언트가 WebSocket 핸드셰이크를 완료하고 성공적으로 연결되면 서비스가 Upstream을 호출합니다.

ce-type: azure.webpubsub.sys.connected
Content-Type: application/json
ce-connectionState: eyJrZXkiOiJhIn0=

요청 본문이 빈 JSON입니다.

요청 형식:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

응답 형식:

2xx: 성공 응답

connected는 비동기 이벤트입니다. 응답 상태 코드가 성공하지 않으면 서비스에서 오류를 기록합니다.

HTTP/1.1 200 OK

시스템 `disconnected` 이벤트

disconnected이벤트는 connect 이벤트가 상태 코드를 반환 2xx 하는 경우 클라이언트 요청이 완료될 때 항상 트리거됩니다.

ce-type: azure.webpubsub.sys.disconnected
Content-Type: application/json

요청 형식:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

reason

클라이언트 reason 의 연결이 끊어진 이유를 설명합니다.

응답 형식:

2xx: 성공 응답

disconnected는 비동기 이벤트입니다. 응답 상태 코드가 성공하지 않으면 서비스에서 오류를 기록합니다.

HTTP/1.1 200 OK

단순 WebSocket 클라이언트에 대한 사용자 이벤트 `message`

서비스는 모든 WebSocket 메시지 프레임에 대한 이벤트 처리기 업스트림 호출합니다.

ce-type: azure.webpubsub.user.message
Content-Type: 바이너리 프레임의 경우 application/octet-stream, 텍스트 프레임의 경우 text/plain

UserPayload는 클라이언트가 보내는 것입니다.

요청 형식:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

성공 응답 형식

상태 코드
- 204: 성공, 콘텐츠가 없습니다.
- 200: 성공, 형식은 UserResponsePayload 응답에 Content-Type 따라 달라집니다.
Content-Type: 바이너리 프레임의 경우 application/octet-stream, 텍스트 프레임의 경우 text/plain
헤더 Content-Type: 이진 파일 프레임의 경우 application/octet-stream, 텍스트 프레임의 경우 text/plain
헤더 ce-connectionState: 이 헤더가 있으면 이 연결의 연결 상태가 헤더 값으로 업데이트됩니다. 차단 이벤트만 연결 상태를 업데이트할 수 있습니다. 아래 샘플은 base64로 인코딩된 JSON 문자열을 사용하여 연결에 대한 복잡한 상태를 저장합니다.

Content-Type이 application/octet-stream이면 서비스는 binary WebSocket 프레임을 사용하여 클라이언트에 UserResponsePayload를 보냅니다. Content-Type이 text/plain이면 서비스는 text WebSocket 프레임을 사용하여 클라이언트에 UserResponsePayload를 보냅니다.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

오류 응답 형식

상태 코드가 성공하지 않으면 오류 응답으로 간주됩니다. 응답 상태 코드가 message 성공하지 않으면 연결이 삭제됩니다.

PubSub WebSocket 클라이언트에 대한 사용자 지정 이벤트 `{custom_event}`

서비스는 유효한 모든 사용자 지정 이벤트 메시지에 대해 이벤트 처리기 웹후크를 호출합니다.

사례 1: 텍스트 데이터와 함께 이벤트 보내기:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "text",
    "data": "text data"
}

업스트림 이벤트 처리기가 아래 Content-Type 와 같이 수신하는 것은 CloudEvents HTTP 요청에 text/plain 대한 것입니다.dataType=text

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

사례 2: JSON 데이터로 이벤트 보내기:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    },
}

업스트림 이벤트 처리기가 아래 Content-Type 와 같이 수신하는 것은 CloudEvents HTTP 요청에 application/json 대한 것입니다.dataType=json

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

사례 3: 이진 데이터와 함께 이벤트 보내기:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

업스트림 이벤트 처리기가 아래 Content-Type 와 같이 수신하는 것은 CloudEvents HTTP 요청에 application/octet-stream 대한 것입니다.dataType=binary

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

성공 응답 형식

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

상태 코드
- 204: 성공, 콘텐츠가 없습니다.
- 200: 성공, PubSub WebSocket 클라이언트로 전송되는 데이터는 ;에 Content-Type따라 달라집니다.
헤더 ce-connectionState: 이 헤더가 있으면 이 연결의 연결 상태가 헤더 값으로 업데이트됩니다. 차단 이벤트만 연결 상태를 업데이트할 수 있습니다. 아래 샘플은 base64로 인코딩된 JSON 문자열을 사용하여 연결에 대한 복잡한 상태를 저장합니다.
헤더 Content-Type이 application/octet-stream인 경우 서비스는 페이로드 base64로 인코딩된 binary로 dataType을 사용하여 클라이언트에 UserResponsePayload를 다시 보냅니다. 샘플 응답:
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Content-Type이 text/plain이면 서비스는 dataType을 페이로드 문자열과 함께 text로 사용하여 UserResponsePayload를 클라이언트에 보냅니다.
이 Content-Type application/json경우 서비스는 응답 페이로드 본문으로 값 토큰을 data 사용하여 dataType=json 클라이언트로 보냅니 UserResponsePayload 다.

오류 응답 형식

상태 코드가 성공하지 않으면 오류 응답으로 간주됩니다. 응답 상태 코드가 {custom_event} 성공하지 않으면 연결이 삭제됩니다.

다음 단계

다음 리소스를 사용하여 사용자 고유의 애플리케이션 빌드를 시작합니다.

자습서: Azure Web PubSub에서 메시지 게시 및 구독

자습서: Azure Web PubSub를 사용하여 간단한 채팅방 만들기

자습서: 클라이언트 스트리밍에 서비스 지원 하위 프로토콜 사용

자습서: Azure Functions 및 Web PubSub를 사용하여 서버리스 채팅 빌드

자습서: 이벤트 수신기 구성

라이브 데모로 재생

Azure Web PubSub 샘플 자세히 살펴보기

다음을 통해 공유

HTTP 프로토콜을 사용하는 Azure Web PubSub 이벤트 처리기용 CloudEvents 확장

웹후크 유효성 검사

Web PubSub CloudEvents 특성 확장

특성

이벤트

시스템 `connect` 이벤트

요청 형식:

성공 응답 형식:

오류 응답 형식:

시스템 `connected` 이벤트

요청 형식:

응답 형식:

시스템 `disconnected` 이벤트

요청 형식:

응답 형식:

단순 WebSocket 클라이언트에 대한 사용자 이벤트 `message`

요청 형식:

성공 응답 형식

오류 응답 형식

PubSub WebSocket 클라이언트에 대한 사용자 지정 이벤트 `{custom_event}`

사례 1: 텍스트 데이터와 함께 이벤트 보내기:

사례 2: JSON 데이터로 이벤트 보내기:

사례 3: 이진 데이터와 함께 이벤트 보내기:

성공 응답 형식

오류 응답 형식

다음 단계

피드백

추가 리소스

다음을 통해 공유

HTTP 프로토콜을 사용하는 Azure Web PubSub 이벤트 처리기용 CloudEvents 확장

웹후크 유효성 검사

Web PubSub CloudEvents 특성 확장

특성

이벤트

시스템 connect 이벤트

요청 형식:

성공 응답 형식:

오류 응답 형식:

시스템 connected 이벤트

요청 형식:

응답 형식:

시스템 disconnected 이벤트

요청 형식:

응답 형식:

단순 WebSocket 클라이언트에 대한 사용자 이벤트 message

요청 형식:

성공 응답 형식

오류 응답 형식

PubSub WebSocket 클라이언트에 대한 사용자 지정 이벤트 {custom_event}

사례 1: 텍스트 데이터와 함께 이벤트 보내기:

사례 2: JSON 데이터로 이벤트 보내기:

사례 3: 이진 데이터와 함께 이벤트 보내기:

성공 응답 형식

오류 응답 형식

다음 단계

피드백

추가 리소스

시스템 `connect` 이벤트

시스템 `connected` 이벤트

시스템 `disconnected` 이벤트

단순 WebSocket 클라이언트에 대한 사용자 이벤트 `message`

PubSub WebSocket 클라이언트에 대한 사용자 지정 이벤트 `{custom_event}`