Azure Web PubSub 신뢰할 수 있는 JSON WebSocket 하위 프로토콜

JSON WebSocket 하위 프로토콜 json.reliable.webpubsub.azure.v1을 사용하면 업스트림 서버로 왕복하지 않고 서비스를 통해 클라이언트 간에 직접 게시/구독 메시지를 매우 안정적으로 교환할 수 있습니다.

이 문서에서는 하위 프로토콜 json.reliable.webpubsub.azure.v1을 설명합니다.

간헐적인 네트워크 문제로 인해 Websocket 클라이언트 연결이 끊어지면 메시지가 손실될 수 있습니다. 게시자/하위 시스템에서 게시자는 구독자와 분리되어 있으며 구독자의 연결이 끊어지거나 메시지가 손실되는 것을 감지하지 못할 수 있습니다.

일시적인 네트워크 문제를 극복하고 신뢰할 수 있는 메시지 전달을 유지하려면 Azure WebPubSub json.reliable.webpubsub.azure.v1 하위 프로토콜을 사용하여 신뢰할 수 있는 PubSub WebSocket 클라이언트를 만들 수 있습니다.

신뢰할 수 있는 PubSub WebSocket 클라이언트는 다음을 수행할 수 있습니다.

  • 일시적인 네트워크 문제에서 연결을 복구합니다.
  • 메시지 손실을 복구합니다.
  • 조인 요청을 사용하여 그룹에 조인합니다.
  • 휴가 요청을 사용하여 그룹을 유지합니다.
  • 게시 요청을 사용하여 그룹에 직접 메시지를 게시합니다.
  • 이벤트 요청을 사용하여 메시지를 다른 업스트림 이벤트 처리기로 라우팅합니다.

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

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

게시자 및 구독자 클라이언트를 위해 다시 연결 및 메시지 안정성을 구현하려면 신뢰할 수 있는 클라이언트를 만드는 방법을 참조하세요.

클라이언트가 이 하위 프로토콜을 사용할 때 나가고 들어오는 데이터 프레임 모두 JSON 페이로드를 포함해야 합니다.

사용 권한

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

역할 Permission
지정되지 않음 클라이언트는 이벤트 요청을 보낼 수 있습니다.
webpubsub.joinLeaveGroup 클라이언트는 모든 그룹에 가입/탈퇴할 수 있습니다.
webpubsub.sendToGroup 클라이언트는 모든 그룹에 메시지를 게시할 수 있습니다.
webpubsub.joinLeaveGroup.<group> 클라이언트는 <group> 그룹에 조인하거나 탈퇴할 수 있습니다.
webpubsub.sendToGroup.<group> 클라이언트는 <group> 그룹에 메시지를 게시할 수 있습니다.
webpubsub.joinLeaveGroups.<pattern> 클라이언트는 이름이 일치하는 <pattern> 모든 그룹에 가입/탈퇴할 수 있습니다( 와일드카드 그룹 역할 패턴 참조).
webpubsub.sendToGroups.<pattern> 클라이언트는 이름이 일치하는 <pattern> 모든 그룹에 메시지를 게시할 수 있습니다(와일드카드 그룹 역할 패턴 참조).

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

메모

와일드카드 역할(예: webpubsub.sendToGroups.<pattern>)은 런타임 동안 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은 text/plain이 dataType인 경우 text입니다.

사례 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은 application/json이 dataType인 경우 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은 application/octet-stream이 dataType인 경우 binary입니다. WebSocket 프레임은 텍스트 메시지 프레임의 경우 text 형식이거나 binary 메시지 프레임의 경우 UTF8로 인코딩된 이진일 수 있습니다.

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

Ping

형식:

{
    "type": "ping",
}

클라이언트는 서비스에 메시지를 보내 ping Web PubSub 서비스가 클라이언트의 활동성을 감지할 수 있도록 할 수 있습니다.

시퀀스 Ack

형식:

{
    "type": "sequenceAck",
    "sequenceId": "<sequenceId>",
}

신뢰할 수 있는 PubSub WebSocket 클라이언트는 서비스에서 메시지를 받으면 시퀀스 ack 메시지를 보내야 합니다. 자세한 내용은 신뢰할 수 있는 클라이언트를 만드는 방법을 참조하세요.

  • sequenceId는 받은 메시지의 증분 uint64 숫자입니다.

응답

클라이언트에서 받은 메시지는 다음과 같은 여러 형식일 수 있습니다. ackmessagesystempong message 형식이 있는 메시지에는 sequenceId 속성이 있습니다. 클라이언트에서 메시지를 받으면 시퀀스 Ack를 서비스에 보내야 합니다.

ack 응답

요청에 ackId가 포함된 경우 서비스는 이 요청에 대한 ack 응답을 반환합니다. 클라이언트 구현은 작업을 사용하여 ack 응답을 기다리는 것을 포함하여 이 ack 메커니즘을 asyncawait 처리해야 하며, 특정 기간 동안 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>"
    }
}

클라이언트 구현에서는 먼저 success가 true인지 아니면 false인지 항상 확인해야 합니다. success가 false이면 클라이언트가 error에서 읽습니다.

메시지 응답

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

  1. 그룹의 응답 메시지:

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

  2. 서버의 응답 메시지:

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

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

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

  • PubSub WebSocket 클라이언트는 JSON으로 메시지를 받습니다.

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

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

  • 간단한 WebSocket 클라이언트는 문자열화된 데이터({ "Hello" : "World"})가 포함된 텍스트 WebSocket 프레임을 수신합니다.

  • PubSub WebSocket 클라이언트는 JSON으로 메시지를 받습니다.

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

REST API가 Hello World 콘텐츠 형식을 사용하여 application/json 문자열을 전송하는 경우 단순 WebSocket 클라이언트는 "Hello World"로 묶인 " JSON 문자열을 수신합니다.

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

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

  • PubSub WebSocket 클라이언트는 JSON으로 메시지를 받습니다.

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

시스템 응답

Web PubSub 서비스에서는 시스템 관련 응답을 클라이언트에 반환할 수 있습니다.

탁구 응답

Web PubSub 서비스는 클라이언트에서 메시지를 받으면 클라이언트에 pong 메시지를 보냅니 ping 다.

형식:

{
    "type": "pong",
}

연결됨

클라이언트 연결 요청에 대한 응답:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
    "reconnectionToken": "<token>"
}

connectionId 및 reconnectionToken은 다시 연결하는 데 사용됩니다. 다시 연결을 위해 URI를 사용하여 연결 요청을 수행합니다.

wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>

자세한 내용은 연결 복구에서 알아보세요.

연결 끊김

서버에서 연결을 닫거나 서비스가 클라이언트 연결을 거부하는 경우 응답:

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

다음 단계

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

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

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

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

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

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

라이브 데모로 재생

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

  • Last updated on