다음을 통해 공유


Azure Web PubSub 서비스 내부

Azure Web PubSub 서비스에서는 단순 WebSocket 연결을 사용하여 메시지를 손쉽게 게시/구독하는 방법을 제공합니다.

  • 클라이언트는 WebSocket이 지원되는 모든 언어로 작성할 수 있습니다.
  • 하나의 연결 내에서 텍스트와 이진 메시지 모두 지원
  • 간단한 프로토콜을 사용하면 클라이언트가 마사지를 서로에게 직접 게시할 수 있습니다.
  • 서비스에서 WebSocket 연결을 관리함

사용 약관

  • 서비스: Azure Web PubSub 서비스입니다.
  • 연결: 클라이언트 또는 클라이언트 연결이라고도 하는 연결은 클라이언트와 Web PubSub 서비스 간의 논리적 관계입니다. '연결'을 통해 클라이언트와 서비스는 일련의 상태 저장 상호 작용에 참여합니다. 다른 프로토콜을 사용하는 연결은 다르게 동작할 수 있습니다. 예를 들어, 일부 연결은 네트워크 연결 기간으로 제한되는 반면 다른 연결은 클라이언트와 서비스 간의 여러 연속 네트워크 연결을 통해 확장될 수 있습니다.

  • 허브: 허브는 일련의 클라이언트 연결에 대한 논리적 개념입니다. 일반적으로 하나의 시나리오에 대해 하나의 허브를 사용합니다(예: 채팅 허브 또는 알림 허브). 클라이언트 연결이 연결되면 허브에 연결되고, 해당 수명 동안 해당 허브에 속합니다. 클라이언트 연결이 허브에 연결되면 허브가 존재합니다. 애플리케이션마다 서로 다른 허브 이름을 사용하여 하나의 Azure Web PubSub 서비스를 공유할 수 있습니다. 허브 수에는 엄격한 제한이 없지만 허브그룹에 비해 더 많은 서비스 부하를 사용합니다. 동적으로 생성하는 대신 미리 결정된 허브 집합을 사용하는 것이 좋습니다.

  • 그룹: 그룹은 허브에 대한 연결의 하위 집합입니다. 그룹에 클라이언트 연결을 추가하거나 원하는 경우 그룹에서 클라이언트 연결을 제거할 수 있습니다. 예를 들어 클라이언트가 채팅방에 참가하거나 채팅방에서 나가면 이 채팅방이 그룹일 수 있습니다. 클라이언트는 여러 그룹에 참가할 수 있으며, 한 그룹에 여러 클라이언트가 포함될 수 있습니다. 그룹은 그룹 "세션"과 같습니다. 그룹 세션은 누군가가 그룹에 조인하면 만들어지고 그룹에 아무도 없으면 세션이 사라집니다. 그룹에 보낸 메시지는 그룹에 연결된 모든 클라이언트에 전달됩니다.

  • 사용자: Web PubSub에 대한 연결은 한 명의 사용자에게 속할 수 있습니다. 단일 사용자가 여러 디바이스 또는 여러 브라우저 탭에서 연결된 경우와 같이 사용자에게 여러 연결이 있을 수 있습니다.

  • 메시지: 클라이언트가 연결되면 메시지를 업스트림 애플리케이션으로 보내거나 WebSocket 연결을 통해 업스트림 애플리케이션에서 메시지를 받을 수 있습니다. 메시지는 일반 텍스트, 이진 파일 또는 JSON 형식일 수 있으며 최대 크기는 1MB입니다.

  • 클라이언트 이벤트: 이벤트는 클라이언트 연결의 수명 주기 동안 생성됩니다. 예를 들어 단순 WebSocket 클라이언트 연결에서는 서비스에 연결하려고 하면 connect 이벤트, 서비스에 성공적으로 연결되면 connected 이벤트, 서비스에 메시지를 보낼 때 message 이벤트, 서비스에서 연결이 끊어지면 disconnected 이벤트가 생성됩니다. 클라이언트 이벤트에 대한 세부 정보는 클라이언트 프로토콜 섹션에 설명되어 있습니다.

  • 이벤트 처리기: 이벤트 처리기에는 클라이언트 이벤트를 처리하는 논리가 포함되어 있습니다. 포털이나 Azure CLI를 통해 미리 서비스에 이벤트 처리기를 등록하고 구성합니다. 세부 정보는 이벤트 처리기 섹션에 설명되어 있습니다.

  • 이벤트 수신기(미리 보기): 이벤트 수신기는 클라이언트 이벤트를 수신하지만 응답을 통해 클라이언트의 수명을 방해할 수는 없습니다. 자세한 내용은 이벤트 수신기 섹션에 설명되어 있습니다.

  • 서버: 서버는 클라이언트 이벤트를 처리하거나, 클라이언트 연결을 관리하거나, 그룹에 메시지를 게시할 수 있습니다. 이벤트 처리기와 이벤트 수신기는 모두 서버 쪽으로 간주됩니다. 서버에 대한 자세한 내용은 서버 프로토콜 섹션에 설명되어 있습니다.

워크플로

Web PubSub 서비스 워크플로를 보여 주는 다이어그램

위의 그래프와 같은 작업 흐름:

  1. 클라이언트는 WebSocket 전송을 사용하여 서비스 /client 엔드포인트에 연결합니다. 서비스는 모든 WebSocket 프레임을 구성된 업스트림(서버)으로 전달합니다. WebSocket 연결은 서버가 처리할 사용자 지정 하위 프로토콜과 연결하거나 클라이언트가 직접 게시/구독을 수행할 수 있는 서비스 지원 하위 프로토콜 json.webpubsub.azure.v1과 연결할 수 있습니다. 세부 정보는 클라이언트 프로토콜에 설명되어 있습니다.
  2. 다른 클라이언트 이벤트에서 서비스는 CloudEvents 프로토콜을 사용하여 서버를 호출합니다. CloudEvents는 CNCF(Cloud Native Computing Foundation)에서 호스트하는 이벤트의 구조 및 메타데이터 설명에 대한 표준화된 프로토콜 독립적 정의입니다. CloudEvents 프로토콜의 자세한 구현은 서버 프로토콜에 설명된 서버 역할에 의존합니다.
  3. Web PubSub 서버는 REST API를 사용하여 서비스를 호출하여 클라이언트에 메시지를 보내거나 연결된 클라이언트를 관리할 수 있습니다. 세부 정보는 서버 프로토콜에 설명되어 있습니다.

클라이언트 프로토콜

클라이언트 연결은 WebSocket 프로토콜을 사용하여 서비스의 /client 엔드포인트에 연결합니다. WebSocket 프로토콜은 단일 TCP 연결을 통해 전이중 통신 채널을 제공하며 2011년에 IETF에서 RFC 6455로 표준화했습니다. 대부분의 언어에는 WebSocket 연결을 시작하는 기본 지원을 제공합니다.

이 서비스는 다음 두 가지 종류의 클라이언트를 지원합니다.

단순 WebSocket 클라이언트

이름에서 알 수 있듯이 간단한 WebSocket 클라이언트는 단순 WebSocket 연결입니다. 또한 사용자 지정 하위 프로토콜을 가질 수 있습니다.

예를 들어, JS에서 다음 코드를 사용하여 간단한 WebSocket 클라이언트를 만들 수 있습니다.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

다음 시퀀스 다이어그램과 같이 간단한 WebSocket 클라이언트는 클라이언트<->서버 아키텍처를 따릅니다. 클라이언트 연결 시퀀스를 보여 주는 다이어그램.

  1. 클라이언트가 WebSocket 핸드셰이크를 시작하면 서비스는 WebSocket 핸드셰이크에 대한 connect 이벤트 처리기 호출을 시도합니다. 개발자는 이 처리기를 사용하여 WebSocket 핸드셰이크를 처리하고, 사용할 하위 프로토콜을 결정하고, 클라이언트를 인증하고, 클라이언트를 그룹에 조인시킬 수 있습니다.
  2. 클라이언트가 성공적으로 연결되면 서비스가 connected 이벤트 처리기를 호출합니다. 알림으로 작동하며 클라이언트가 메시지를 보내는 것을 차단하지 않습니다. 개발자는 이 처리기를 사용하여 데이터 저장을 수행하고 클라이언트에 대한 메시지로 응답할 수 있습니다. 또한 서비스는 모든 관련 이벤트 수신기(있는 경우)에 connected 이벤트를 푸시합니다.
  3. 클라이언트가 메시지를 보내면 서비스는 이벤트 처리기에 이벤트를 트리거합니다 message . 이 이벤트에는 WebSocket 프레임에서 보낸 메시지가 포함됩니다. 코드는 이 이벤트 처리기 내에서 메시지를 발송해야 합니다. 이벤트 처리기가 비정상 응답 코드를 반환하는 경우 서비스는 클라이언트 연결을 삭제합니다. 또한 서비스는 모든 관련 이벤트 수신기(있는 경우)에 이벤트를 푸시 message 합니다. 서비스에서 메시지를 받을 등록된 서버를 찾을 수 없는 경우 서비스는 클라이언트 연결도 삭제합니다.
  4. 클라이언트의 연결이 끊어지면 서비스는 연결이 끊어진 것을 검색하면 이벤트 처리기에 disconnected 이벤트를 트리거하려고 시도합니다. 또한 서비스는 모든 관련 이벤트 수신기(있는 경우)에 disconnected 이벤트를 푸시합니다.

시나리오

이러한 연결은 클라이언트가 서버에 메시지를 보내고 서버가 이벤트 처리기를 사용하여 들어오는 메시지를 처리하는 일반적인 클라이언트-서버 아키텍처에서 사용할 수 있습니다. 고객이 애플리케이션 로직에 기존 하위 프로토콜을 적용할 때도 사용할 수 있습니다.

PubSub WebSocket 클라이언트

이 서비스는 클라이언트가 업스트리밍 서버로의 왕복 대신 직접 게시/구독을 수행할 수 있도록 하는 json.webpubsub.azure.v1이라는 특정 하위 프로토콜도 지원합니다. json.webpubsub.azure.v1 하위 프로토콜을 사용하는 WebSocket 연결을 PubSub WebSocket 클라이언트라고 합니다. 자세한 내용은 GitHub의 Web PubSub 클라이언트 사양을 참조하세요.

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

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

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

  • 그룹에 가입합니다. 예를 들면 다음과 같습니다.

    {
      "type": "joinGroup",
      "group": "<group_name>"
    }
    
  • 그룹에서 탈퇴합니다. 예를 들면 다음과 같습니다.

    {
      "type": "leaveGroup",
      "group": "<group_name>"
    }
    
  • 그룹에 메시지를 게시합니다. 예를 들면 다음과 같습니다.

    {
      "type": "sendToGroup",
      "group": "<group_name>",
      "data": { "hello": "world" }
    }
    
  • 업스트림 서버에 사용자 지정 이벤트를 보냅니다. 예를 들면 다음과 같습니다.

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

PubSub WebSocket 하위 프로토콜에는 json.webpubsub.azure.v1 하위 프로토콜의 세부 정보가 포함되어 있습니다.

간단한 WebSocket 클라이언트의 경우 서버클라이언트에서 이벤트를 수신 message 하는 역할이 있어야 합니다. 항상 단순 WebSocket 연결은 메시지를 보낼 때 message 이벤트를 트리거하며 서버 측에 의존하여 메시지를 처리하고 다른 작업을 수행합니다. json.webpubsub.azure.v1 하위 프로토콜을 사용하면 권한 부여된 클라이언트가 그룹에 가입하고 그룹에 직접 메시지를 게시할 수 있습니다. 또한 메시지가 속한 이벤트를 사용자 지정하여 다른 이벤트 처리기/이벤트 수신기로 메시지를 라우팅할 수도 있습니다.

시나리오

이러한 클라이언트는 클라이언트가 서로 대화하려고 할 때 사용할 수 있습니다. 메시지는 client2에서 서비스로 전송되고, 클라이언트에 해당 권한이 있는 경우 서비스에서 client1에 직접 메시지를 전달합니다.

Client1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Client2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

위의 예제에서 볼 수 있듯이 client2client1이 있는 Group1에 메시지를 게시하여 client1에 직접 데이터를 보냅니다.

클라이언트 이벤트 요약

클라이언트 이벤트는 두 가지 범주로 나뉩니다.

  • 동기 이벤트(차단) 동기 이벤트는 클라이언트 워크플로를 차단합니다.

    • connect: 이 이벤트는 이벤트 처리기 전용입니다. 클라이언트가 WebSocket 핸드셰이크를 시작하면, 이벤트가 트리거되고 개발자는 connect 이벤트 처리기를 사용하여 WebSocket 핸드셰이크를 처리하고, 사용할 하위 프로토콜을 결정하고, 클라이언트를 인증하고, 클라이언트를 그룹에 조인시킬 수 있습니다.
    • message: 이 이벤트는 클라이언트가 메시지를 보낼 때 트리거됩니다.
  • 비동기 이벤트(비차단) 비동기 이벤트는 클라이언트 워크플로를 차단하지 않습니다. 대신 서버에 알림을 보냅니다. 해당 이벤트 트리거가 실패하면 서비스는 오류 세부 정보를 기록합니다.

    • connected: 이 이벤트는 클라이언트가 서비스에 성공적으로 연결될 때 트리거됩니다.
    • disconnected: 이 이벤트는 클라이언트가 서비스와의 연결이 끊어졌을 때 트리거됩니다.

클라이언트 메시지 한도

하나의 WebSocket 프레임에 허용되는 최대 메시지 크기는 1MB입니다.

클라이언트 인증

인증 워크플로

클라이언트는 서명된 JWT 토큰을 사용하여 서비스에 연결합니다. 수신 클라이언트의 connect 이벤트 처리기인 경우 업스트림에서 클라이언트를 거부할 수도 있습니다. 이벤트 처리기는 클라이언트가 웹후크 응답에 있는 userIdrole을 지정하여 클라이언트를 인증하거나 401로 클라이언트를 거부합니다. 이벤트 처리기 섹션에서 자세히 설명합니다.

다음 그래프는 워크플로를 설명합니다.

클라이언트 인증 워크플로를 보여 주는 다이어그램

클라이언트는 권한이 부여된 경우에만 다른 클라이언트에 게시할 수 있습니다. role클라이언트는 클라이언트에 있는 초기 사용 권한을 결정합니다.

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

서버 측에서는 이후 섹션에서 설명하는 대로 서버 프로토콜을 통해 동적으로 클라이언트의 권한을 부여하거나 취소할 수도 있습니다.

서버 프로토콜

서버 프로토콜은 서버가 클라이언트 이벤트를 처리하고 클라이언트 연결 및 그룹을 관리하는 기능을 제공합니다.

일반적으로 서버 프로토콜에는 세 가지 역할이 있습니다.

  1. 이벤트 처리기
  2. Connection manager
  3. 이벤트 수신기

이벤트 처리기

이벤트 처리기는 수신 클라이언트 이벤트를 처리합니다. 이벤트 처리기는 포털 또는 Azure CLI를 통해 서비스에 등록 및 구성됩니다. 클라이언트 이벤트가 트리거되면 서비스는 이벤트를 처리할지 여부를 식별할 수 있습니다. 이제 PUSH 모드를 사용하여 이벤트 처리기를 호출합니다. 서버 쪽의 이벤트 처리기는 이벤트가 트리거될 때 호출할 서비스에 대해 공개적으로 액세스 가능한 엔드포인트를 노출합니다. 웹후크 역할을 합니다.

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

모든 이벤트에 대해 서비스는 등록된 업스트림에 대한 HTTP POST 요청을 수식화하고 HTTP 응답을 기대합니다.

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

Web PubSub 서비스 이벤트 푸시 모드를 보여 주는 다이어그램

업스트림 및 유효성 검사

이벤트 처리기는 처음 사용하기 전에 포털 또는 Azure CLI를 통해 서비스에 등록 및 구성해야 합니다. 클라이언트 이벤트가 트리거되면 서비스는 이벤트를 처리해야 하는지 여부를 식별할 수 있습니다. 공개 미리 보기의 경우 PUSH 모드를 사용하여 이벤트 처리기를 호출합니다. 서버 쪽의 이벤트 처리기는 이벤트가 트리거될 때 호출할 서비스에 대해 공개적으로 액세스 가능한 엔드포인트를 노출합니다. 웹후크 업스트림 역할을 합니다.

URL은 {event} 매개 변수를 사용하여 웹후크 처리기에 대한 URL 템플릿을 정의할 수 있습니다. 서비스는 클라이언트 요청이 들어올 때 웹후크 URL의 값을 동적으로 계산합니다. 예를 들어 허브 chat에 맞게 구성된 이벤트 처리기 URL 패턴 http://host.com/api/{event}와 함께 요청 /client/hubs/chat가 들어오면 클라이언트가 연결할 때 먼저 이 URL http://host.com/api/connect에 POST합니다. 이 동작은 PubSub WebSocket 클라이언트가 사용자 지정 이벤트를 보낼 때 유용할 수 있습니다. 즉, 이벤트 처리기가 다른 이벤트를 다른 업스트림으로 전달하는 데 도움이 됩니다. {event} 매개 변수는 URL 도메인 이름에서 허용되지 않습니다.

Azure Portal 또는 CLI를 통해 이벤트 처리기 업스트림을 설정할 때 서비스는 CloudEvents 남용 방지를 따라 업스트림 웹후크의 유효성을 검사합니다. 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-RateWebHook-Request-Callback을 지원하지 않습니다.

서비스와 웹후크 간 인증/권한 부여

서비스와 웹후크 간에 보안 인증 및 권한 부여를 설정하려면 다음 옵션과 단계를 고려합니다.

  • 익명 모드
  • 구성된 Webhook URL을 통해 code가 제공되는 단순 인증입니다.
  • Microsoft Entra 권한 부여를 사용합니다. 자세한 내용은 관리 ID 사용 방법을 참조하세요.
  1. Web PubSub 서비스에 대한 ID를 사용하도록 설정합니다.
  2. 웹후크 웹앱을 나타내는 기존 Microsoft Entra 애플리케이션에서 선택합니다.

ODBC 대상 편집기

서버는 기본적으로 권한이 있는 사용자입니다. 이벤트 처리기 역할의 도움으로 서버는 클라이언트의 메타데이터(예: connectionIduserId)를 알고 있으므로 다음을 수행할 수 있습니다.

  • 클라이언트 연결 닫기
  • 클라이언트에 메시지 보내기
  • 동일한 사용자에게 속한 클라이언트에 메시지 보내기
  • 그룹에 클라이언트 추가
  • 동일한 사용자로 인증된 클라이언트를 그룹에 추가
  • 그룹에서 클라이언트 제거
  • 그룹에서 동일한 사용자로 인증된 클라이언트 제거
  • 그룹에 메시지 게시

PubSub 클라이언트에 대한 게시/가입 권한도 부여하거나 취소할 수 있습니다.

  • 일부 특정 그룹 또는 모든 그룹에 게시/조인 권한 부여
  • 일부 특정 그룹 또는 모든 그룹에 대한 게시/조인 권한 해지
  • 클라이언트에 특정 그룹 또는 모든 그룹에 가입 또는 게시할 수 있는 권한이 있는지 확인합니다.

이 서비스는 서버가 연결 관리를 수행할 수 있도록 REST API를 제공합니다.

Web PubSub 서비스 연결 관리자 워크플로를 보여 주는 다이어그램입니다.

자세한 REST API 프로토콜은 여기에 정의되어 있습니다.

이벤트 수신기

참고 항목

이벤트 수신기 기능은 미리 보기 상태입니다.

이벤트 수신기는 들어오는 클라이언트 이벤트를 수신합니다. 각 이벤트 수신기에는 관련된 이벤트의 종류를 지정하는 필터와 이벤트를 보낼 위치에 대한 엔드포인트가 포함되어 있습니다.

현재 Event Hubs를 이벤트 수신기 엔드포인트로 지원합니다.

사전에 이벤트 수신기를 등록해야 클라이언트 이벤트가 트리거될 때 서비스에서 해당 이벤트 수신기로 이벤트를 푸시할 수 있습니다. 이벤트 허브 엔드포인트로 이벤트 수신기를 구성하는 방법은 이 문서를 참조하세요.

여러 이벤트 수신기를 구성할 수 있습니다. 구성 순서는 해당 기능에 영향을 주지 않습니다. 이벤트가 여러 수신기와 일치하면 일치하는 모든 수신기에 이벤트가 디스패치됩니다. 예는 다음 다이어그램을 참조하세요. 예를 들어 4개의 이벤트 수신기를 동시에 구성하는 경우 일치를 수신하는 각 수신기는 이벤트를 처리합니다. 해당 수신기 중 3개와 일치하는 클라이언트 이벤트는 3개의 수신기로 전송되고 나머지 수신기는 무시됩니다.

이벤트 수신기 데이터 흐름 다이어그램 샘플

동일한 이벤트에 대해 이벤트 처리기와 이벤트 수신기를 결합할 수 있습니다. 이 경우 이벤트 처리기와 이벤트 수신기 모두 이벤트를 수신합니다.

Web PubSub 서비스는 Azure Web PubSub용 CloudEvents AMQP 확장을 사용하여 클라이언트 이벤트를 이벤트 수신기에 전달합니다.

요약

이벤트 처리기 역할은 서비스에서 서버로의 통신을 처리하는 반면 관리자 역할은 서버에서 서비스로의 통신을 처리합니다. 두 역할을 결합하면 서비스와 서버 간의 데이터 흐름은 HTTP 프로토콜을 사용하는 다음 다이어그램과 유사합니다.

Web PubSub 서비스 양방향 워크플로를 보여 주는 다이어그램입니다.

다음 단계

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