다음을 통해 공유

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로 설정할 수 있습니다. 또는 binary다음을 jsontext수행합니다.
    • 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"
}
  • 의 간단한 WebSocket 클라이언트는 <group_name> 문자열 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"
    }
}
  • 의 간단한 WebSocket 클라이언트는 <group_name> serialize된 문자열 {"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>", 
}
  • 단순 WebSocket 클라이언트는 <group_name> 이진 프레임에서 이진 데이터를 받습니다.

사용자 지정 이벤트 보내기

형식:

{
    "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

Content-Type CloudEvents HTTP 요청의 경우는 다음과 dataType 같습니다 text/plaintext.

사례 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"
}

Content-Type CloudEvents HTTP 요청의 경우는 다음과 같습니다 dataTypeapplication/json.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

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

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

응답

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

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

Ack 응답

클라이언트 요청에 포함된 ackId경우 서비스는 요청에 대한 ack 응답을 반환합니다. 클라이언트는 ack 응답이 특정 기간에 수신되지 않을 때 작업과 함께 asyncawait 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>"
    }
}

클라이언트 구현은 항상 있는 경우 또는 false 첫 번째인 경우 successtrue 검사 다음 오류만 읽어야 success 합니다false.

메시지 응답

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

  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: 다음을 사용하여 REST API를 통해 연결에 데이터 Hello World 보내기 Content-Type=text/plain

  • 간단한 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 샘플 살펴보기