Azure Web PubSub 지원 JSON WebSocket 하위 프로토콜

  • 아티클

JSON WebSocket 하위 프로토콜 json.webpubsub.azure.v1을 사용하면 업스트림 서버로 왕복하지 않고 서비스를 통해 클라이언트 간에 게시/구독 메시지를 교환할 수 있습니다. 하위 프로토콜을 사용하는 json.webpubsub.azure.v1 WebSocket 연결을 PubSub WebSocket 클라이언트라고 합니다.

개요

간단한 WebSocket 연결은 메시지를 보내고 서버 쪽을 사용하여 메시지를 처리하고 다른 작업을 수행할 때 이벤트를 트리거 message 합니다.

하위 프로토콜을 사용하여 다음을 json.webpubsub.azure.v1 수행할 수 있는 PubSub WebSocket 클라이언트를 만들 수 있습니다.

예를 들어 다음 JavaScript 코드를 사용하여 PubSub WebSocket 클라이언트 를 만들 수 있습니다.

// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');

이 문서에서는 하위 프로토콜 json.webpubsub.azure.v1 요청 및 응답에 대해 설명합니다. 들어오는 데이터 프레임과 나가는 데이터 프레임 모두 JSON 페이로드를 포함해야 합니다.

사용 권한

PubSub WebSocket 클라이언트는 권한 부여된 경우에만 다른 클라이언트에 게시할 수 있습니다. 클라이언트에 할당된 roles는 클라이언트에 부여된 권한을 결정합니다.

역할 Permission
지정되지 않음 클라이언트는 이벤트 요청을 보낼 수 있습니다.
webpubsub.joinLeaveGroup 클라이언트는 모든 그룹에 가입/탈퇴할 수 있습니다.
webpubsub.sendToGroup 클라이언트는 모든 그룹에 메시지를 게시할 수 있습니다.
webpubsub.joinLeaveGroup.<group> 클라이언트는 <group> 그룹에 조인하거나 탈퇴할 수 있습니다.
webpubsub.sendToGroup.<group> 클라이언트는 <group> 그룹에 메시지를 게시할 수 있습니다.

서버는 REST API 또는 서버 SDK를 통해 클라이언트 권한을 동적으로 부여하거나 해지할 수 있습니다.

요청

그룹 가입

형식:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId는 각 요청의 ID이며 고유해야 합니다. 서비스는 요청 처리 결과를 알리기 위해 ack 응답 메시지를 보냅니다. 자세한 내용은 AckId 및 Ack 응답을 참조하세요.

그룹 탈퇴

형식:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId는 각 요청의 ID이며 고유해야 합니다. 서비스는 요청 처리 결과를 알리기 위해 ack 응답 메시지를 보냅니다. 자세한 내용은 AckId 및 Ack 응답을 참조하세요.

메시지 게시

형식:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId는 각 요청의 ID이며 고유해야 합니다. 서비스는 요청 처리 결과를 알리기 위해 ack 응답 메시지를 보냅니다. 자세한 내용은 AckId 및 Ack 응답을 참조하세요.
  • noEcho은(는) 선택 사항입니다. true로 설정하면 이 메시지는 동일한 연결로 다시 에코되지 않습니다. 설정하지 않으면 기본값은 false입니다.
  • dataType은 json, text 또는 binary로 설정될 수 있습니다.
    • json: data는 JSON이 지원하는 모든 유형이 될 수 있으며 그대로 게시됩니다. dataType을 지정하지 않으면 기본값은 json입니다.
    • text: data는 문자열 형식이어야 하며 문자열 데이터가 게시됩니다.
    • binary: data는 base64 형식이어야 하며 이진 데이터가 게시됩니다.

사례 1: 텍스트 데이터 게시:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • <group_name>의 하위 프로토콜 클라이언트는 다음을 수신합니다.
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • <group_name>의 단순 WebSocket 클라이언트는 text data 문자열을 수신합니다.

사례 2: JSON 데이터 게시:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • <group_name>의 하위 프로토콜 클라이언트는 다음을 수신합니다.
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • <group_name>의 단순 WebSocket 클라이언트는 직렬화된 문자열 {"hello": "world"}를 수신합니다.

사례 3: 이진 데이터 게시:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • <group_name>의 하위 프로토콜 클라이언트는 다음을 수신합니다.
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • <group_name>의 단순 WebSocket 클라이언트는 이진 파일 프레임에서 이진 파일 데이터를 수신합니다.

사용자 지정 이벤트 보내기

형식:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId는 각 요청의 ID이며 고유해야 합니다. 서비스는 요청 처리 결과를 알리기 위해 ack 응답 메시지를 보냅니다. 자세한 내용은 AckId 및 Ack 응답을 참조하세요.

dataType은 text, binary, json 중 하나일 수 있습니다.

  • json: 데이터는 json이 지원하는 모든 형식이 될 수 있으며 있는 그대로 게시됩니다. 기본값은 json입니다.
  • text: 데이터는 문자열 형식이며 문자열 데이터가 게시됩니다.
  • binary: 데이터는 base64 형식이며 이진 데이터가 게시됩니다.

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

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

업스트림 이벤트 처리기는 다음과 유사한 데이터를 수신합니다.

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>

text data

CloudEvents HTTP 요청의 Content-Type은 dataType이 text인 경우 text/plain입니다.

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

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

업스트림 이벤트 처리기는 다음과 유사한 데이터를 수신합니다.

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>

{
    "hello": "world"
}

CloudEvents HTTP 요청에 대한 Content-Type은 dataType이 json인 경우 application/json입니다.

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

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_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>

binary

CloudEvents HTTP 요청의 Content-Type은 dataType이 binary인 경우 application/octet-stream입니다. WebSocket 프레임은 텍스트 메시지 프레임의 경우 text 형식이거나 binary 메시지 프레임의 경우 UTF8로 인코딩된 이진일 수 있습니다.

Web PubSub 서비스는 메시지가 설명된 형식과 일치하지 않는 경우 클라이언트를 거부합니다.

응답

클라이언트에서 받은 메시지 유형은 다음과 같습니다.

  • ack - 를 포함하는 요청에 대한 응답입니다 ackId.
  • message - 그룹 또는 서버의 메시지입니다.
  • system - Web PubSub 서비스의 메시지입니다.

ack 응답

클라이언트 요청에 포함된 ackId경우 서비스는 요청에 대한 ack 응답을 반환합니다. 클라이언트는 ack 응답이 특정 기간에 수신되지 않을 때 작업과 함께 async await ack 응답을 대기하고 시간 제한 작업을 사용하여 ack 메커니즘을 처리해야 합니다.

형식:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

클라이언트 구현은 항상 is true 또는 first인지 success 확인한 다음, 오류가 있는 경우에만 success falsefalse 읽어야 합니다.

메시지 응답

클라이언트는 클라이언트가 조인한 그룹 또는 서버 관리 역할에서 작동하여 특정 클라이언트 또는 사용자에게 메시지를 보내는 서버에서 게시된 메시지를 받을 수 있습니다.

  1. 메시지가 그룹에서 오는 경우

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. 메시지가 서버에서 온 경우입니다.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

사례 1: Content-Type=text/plain을 사용하여 REST API를 통해 연결에 데이터 Hello World 보내기

  • 간단한 WebSocket 클라이언트는 Hello World 데이터가 포함된 텍스트 WebSocket 프레임을 수신합니다.

  • PubSub WebSocket 클라이언트는 다음을 받습니다.

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

사례 2: Content-Type=application/json을 사용하여 REST API를 통해 연결에 데이터 { "Hello" : "World"} 보내기

  • 간단한 WebSocket 클라이언트는 문자열화된 데이터가 { "Hello" : "World"}포함된 WebSocket 프레임 텍스트를 받습니다.

  • PubSub WebSocket 클라이언트는 다음을 받습니다.

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

REST API가 콘텐츠 형식을 사용하여 application/json 문자열 Hello World 을 보내는 경우 간단한 WebSocket 클라이언트는 "Hello World" 큰따옴표(")로 래핑되는 JSON 문자열을 받습니다.

사례 3: Content-Type=application/octet-stream을 사용하여 REST API를 통해 연결에 이진 데이터 보내기

  • 간단한 WebSocket 클라이언트는 이진 데이터가 포함된 이진 WebSocket 프레임을 수신합니다.

  • PubSub WebSocket 클라이언트는 다음을 받습니다.

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

시스템 응답

Web PubSub 서비스는 클라이언트에 시스템 관련 메시지를 보냅니다.

연결됨

클라이언트가 성공적으로 연결할 때 클라이언트에 보낸 메시지:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

연결 끊김

서버가 연결을 닫을 때 또는 서비스에서 클라이언트를 거부할 때 클라이언트로 전송되는 메시지입니다.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

다음 단계

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

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

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

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

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

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

라이브 데모로 재생

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