Express용 Azure Web Pubsub CloudEvents 처리기

  • 아티클

Azure Web PubSub 서비스는 개발자가 실시간 기능 및 게시-구독 패턴을 사용하여 웹 애플리케이션을 쉽게 빌드할 수 있도록 도와주는 Azure 관리형 서비스입니다. 서버와 클라이언트 간 또는 클라이언트 간에 실시간 게시-구독 메시징이 필요한 시나리오에서는 Azure Web PubSub 서비스를 사용할 수 있습니다. 서버에서 폴링하거나 HTTP 요청을 제출해야 하는 경우가 많은 기존의 실시간 기능도 Azure Web PubSub 서비스를 사용할 수 있습니다.

WebSocket 연결이 연결되면 Web PubSub 서비스는 연결 수명 주기 및 메시지를 CloudEvents 형식의 이벤트로 변환합니다. 이 라이브러리는 아래 다이어그램과 같이 WebSocket 연결의 수명 주기 및 메시지를 나타내는 이벤트를 처리하는 Express 미들웨어를 제공합니다.

cloudevents

여기에 사용된 용어에 대한 자세한 내용은 주요 개념 섹션에 설명되어 있습니다.

소스 코드 | 패키지(NPM) | API 참조 설명서 | 제품 설명서 | 샘플

시작

현재 지원되는 환경

필수 구성 요소

1. @azure/web-pubsub-express 패키지 설치

npm install @azure/web-pubsub-express

2. WebPubSubEventHandler를 만듭니다.

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

주요 개념

연결

연결: 클라이언트 또는 클라이언트 연결이라고도 하는 연결은 Web PubSub 서비스에 연결된 개별 WebSocket 연결을 나타냅니다. 성공적으로 연결되면 Web PubSub 서비스에서 고유한 연결 ID를 이 연결에 할당합니다.

허브

허브는 클라이언트 연결 집합에 대한 논리적 개념입니다. 일반적으로 하나의 목적에 대해 하나의 허브를 사용합니다(예: 채팅 허브 또는 알림 허브). 클라이언트 연결이 만들어지면 허브에 연결되고 수명 동안 해당 허브에 속합니다. 애플리케이션마다 서로 다른 허브 이름을 사용하여 하나의 Azure Web PubSub 서비스를 공유할 수 있습니다.

그룹

그룹은 허브에 대한 연결의 하위 집합입니다. 그룹에 클라이언트 연결을 추가하거나 원하는 경우 그룹에서 클라이언트 연결을 제거할 수 있습니다. 예를 들어 클라이언트가 채팅방에 참가하거나 채팅방에서 나가면 이 채팅방이 그룹일 수 있습니다. 클라이언트는 여러 그룹에 참가할 수 있으며, 한 그룹에 여러 클라이언트가 포함될 수 있습니다.

사용자

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

클라이언트 이벤트

이벤트는 클라이언트 연결의 수명 주기 동안 생성됩니다. 예를 들어 단순 WebSocket 클라이언트 연결에서는 서비스에 연결하려고 하면 connect 이벤트, 서비스에 성공적으로 연결되면 connected 이벤트, 서비스에 메시지를 보낼 때 message 이벤트, 서비스에서 연결이 끊어지면 disconnected 이벤트가 생성됩니다.

이벤트 처리기

이벤트 처리기에는 클라이언트 이벤트를 처리하는 논리가 포함되어 있습니다. 이벤트 처리기는 미리 포털 또는 Azure CLI를 통해 서비스에 등록 및 구성해야 합니다. 이벤트 처리기 논리를 호스팅하는 위치는 일반적으로 서버 쪽으로 간주됩니다.

예제

connect 요청 처리 및 <userId> 할당

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

지정된 엔드포인트만 허용

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

사용자 지정 이벤트 처리기 경로 설정

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

연결 상태 설정 및 읽기

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

문제 해결

로그 사용 설정

다음 환경 변수를 설정하여 이 라이브러리를 사용할 때 디버그 로그를 볼 수 있습니다.

  • SignalR 클라이언트 라이브러리에서 디버그 로그 가져오기
export AZURE_LOG_LEVEL=verbose

로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.

라이브 추적

Web PubSub 서비스 포털에서 라이브 추적을 사용하여 실시간 트래픽을 확인합니다.

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.