클라이언트의 이벤트 알림
"빠른 시작"의 처음 세 문서에서는 대규모 (백만+) 실시간 메시징을 위해 Web PubSub을 사용하는 두 가지 유용한 통신 패턴을 알아보았습니다.
- 애플리케이션 서버에서 영구 연결 관리의 복잡성이 발생하지 않도록 하는 클라이언트 간의 Pub/Sub
- 새 데이터를 사용할 수 있는 즉시 애플리케이션 서버에서 클라이언트로 메시지 푸시
이 빠른 시작 가이드에서는 다음과 같은 경우에 애플리케이션 서버가 이벤트에 반응할 수 있도록 Web PubSub의 이벤트 시스템에 대해 알아봅니다.
- 클라이언트가
connected인 경우 - 클라이언트가
message를 전송하여 추가 처리가 필요한 경우
Important
원시 연결 문자열 데모용으로만 이 문서에 표시됩니다.
연결 문자열에는 애플리케이션이 Azure Web PubSub 서비스에 액세스하는 데 필요한 권한 부여 정보가 포함됩니다. 연결 문자열 내의 액세스 키는 서비스의 루트 암호와 비슷합니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 연결을 WebPubSubServiceClient보호합니다.
액세스 키를 다른 사용자에게 배포하거나 하드 코딩하거나 다른 사용자가 액세스할 수 있는 일반 텍스트로 저장하지 않도록 합니다. 키가 손상되었다고 생각되면 키를 교체하세요.
필수 조건
- Web PubSub 리소스. 아직 만들지 않은 경우 Web PubSub 리소스 만들기의 지침을 따를 수 있습니다.
- Visual Studio Code와 같은 코드 편집기
- 사용하려는 언어에 대한 종속성 설치
애플리케이션 만들기
Web PubSub는 애플리케이션 서버에 대한 독립 실행형 서비스입니다. 애플리케이션은 기존 HTTP 서버로서의 역할을 유지하지만 Web PubSub은 애플리케이션 서버와 클라이언트 간에 전달되는 실시간 메시지를 처리합니다. 먼저 클라이언트 프로그램을 만든 다음, 서버 프로그램을 만듭니다.
클라이언트 만들기
1. 클라이언트 앱에서 디렉터리 만들기
mkdir eventHandlerDemo
cd eventHandlerDemo
# The SDK is available as an NPM module.
npm install @azure/web-pubsub-client
2. Web PubSub에 연결
브라우저, 모바일 앱 또는 IoT 디바이스에 해당하는 클라이언트는 클라이언트 액세스 URL을 사용하여 리소스에 연결하고 인증합니다.
이 URL은 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>의 패턴을 따릅니다.
클라이언트는 클라이언트 액세스 URL을 가져오는 몇 가지 방법을 사용할 수 있습니다. 이 빠른 시작을 위해 다음 다이어그램에 표시된 Azure Portal에서 복사하여 붙여넣을 수 있습니다. 코드에서 클라이언트 액세스 URL을 하드 코딩하지 않는 것이 가장 좋습니다. 프로덕션 환경에서는 일반적으로 요청 시 이 URL을 반환하도록 앱 서버를 설정합니다. 클라이언트 액세스 URL 생성에서는 사례를 자세히 설명합니다.
이름이 client.js인 파일을 만들고 다음 코드를 추가합니다.
const { WebPubSubClient } = require("@azure/web-pubsub-client");
// Instantiates the client object
// <client-access-url> is copied from Azure portal mentioned above.
const client = new WebPubSubClient("<client-access-url>");
// Registers a handler to the "connected" event
client.on("connected", (e) => {
console.log(`Connection ${e.connectionId} is connected.`);
});
// You must invoke start() on the client object
// to establish connection with your Web PubSub resource
client.start();
애플리케이션 서버 만들기
1. express.js 및 Web PubSub 서버 SDK 설치
npm init -y
npm install --save express
# Installs the middleware from Web PubSub. This middleware will set up an endpoint for you.
npm install --save @azure/web-pubsub-express
2. 빈 Express 앱을 설정하는 "server.js"라는 새 파일 만들기
const express = require("express");
const app = express();
app.listen(8080, () => console.log('Server started, listening on port 8080'));
3. 이벤트 처리
Web PubSub을 사용하면 클라이언트 쪽 에서 특정 활동이 발생하는 경우(예: 클라이언트가 Web PubSub 리소스가 connected 또는 disconnected인 경우) 애플리케이션 서버는 이러한 이벤트에 반응하도록 처리기를 설정할 수 있습니다.
다음은 두 가지 주목할 만한 사용 사례입니다.
- 클라이언트가 연결되면 연결된 모든 클라이언트에 이 상태를 브로드캐스트할 수 있습니다.
- 클라이언트가 Web PubSub 리소스에 메시지를 보낼 때 선택한 데이터베이스에 메시지를 유지할 수 있습니다.
const express = require("express");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const app = express();
const HUB_NAME = "myHub1";
let handler = new WebPubSubEventHandler(HUB_NAME, {
path: '/eventhandler', // Exposes an endpoint
onConnected: async (req) => {
console.log(`${req.context.userId} connected`);
},
});
// Registers the middleware with the express app
app.use(handler.getMiddleware());
app.listen(8080, () => console.log('Server started, listening on port 8080'));
위의 코드에서 구성한 대로 클라이언트가 Web PubSub 리소스와 연결되면 Web PubSub는 경로 /eventhandler에서 애플리케이션 서버가 제공하는 웹후크를 호출합니다. 여기서는 사용자가 연결되면 콘솔에 userId를 출력하기만 하면 됩니다.
localhost 노출
프로그램을 실행합니다. 포트 8080의 localhost에서 실행 중이어야 합니다. 이 작업의 경우 로컬 Express 앱이 인터넷에서 도달할 수 없다는 것을 의미합니다. 따라서 Web PubSub은 경로 /eventhandler에 제공된 웹후크를 호출할 수 없습니다.
트래픽을 localhost로 라우팅하는 방법은 두 가지가 있습니다. 하나는 ngrok 및 TunnelRelay와 같은 도구를 사용하여 인터넷에서 액세스할 수 있도록 localhost를 노출하는 것입니다. 또 다른 방법이자 권장되는 방법은 awps-tunnel을 사용하여 도구를 통해 Web PubSub 서비스에서 로컬 서버로 트래픽을 터널링하는 것입니다.
1. awps-tunnel 다운로드 및 설치
이 도구는 Node.js 버전 16 이상에서 실행됩니다.
npm install -g @azure/web-pubsub-tunnel-tool
2. 서비스 연결 문자열 사용 및 실행
원시 연결 문자열 데모용으로만 이 문서에 표시됩니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 연결을 WebPubSubServiceClient보호합니다.
export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub myHub1 --upstream http://localhost:8080
Web PubSub 리소스에서 이벤트 처리기 설정
이제 Web PubSub 리소스에서 이 웹후크 URL에 대해 알 수 있도록 해야 합니다. Azure Portal 또는 Azure CLI에서 이벤트 처리기를 설정할 수 있습니다.
메뉴에서 "설정"을 선택하고 "추가"
를 선택합니다.
허브 이름을 입력합니다. 이 작업에서는 "myHub1"을 입력하고 "추가"를 선택합니다.
이벤트 처리기 페이지에서 다음 필드를 구성합니다.
awps-tunnel도구를 사용하는 경우 URL 템플릿은tunnel체계와tunnel:///eventhandler
경로를 사용합니다.
구성 저장
프로그램 실행
애플리케이션 서버 시작
node server.js
클라이언트 프로그램 시작
node client.js
결과 확인
콘솔에 userId가 출력된 것을 볼 수 있습니다.
메시지 이벤트 처리
클라이언트는 connect, connected, disconnected와 같은 시스템 이벤트 외에 custom 이벤트도 보낼 수 있습니다.
클라이언트 프로그램 수정
클라이언트 프로그램을 중지하고 client.js에 다음 코드를 추가합니다.
// ...code from before
client.start();
// The name of the event is message and the content is in text format.
client.sendEvent("message", "sending custom event!", "text");
서버 프로그램 수정
클라이언트 프로그램을 중지하고 다음 코드를 server.js에 추가합니다.
// ... code from before
let handler = new WebPubSubEventHandler(HUB_NAME, {
path: "/eventhandler",
onConnected: async (req) => {
console.log(`"${req.context.userId}" is connected.`);
},
// This handler function will handle user system
handleUserEvent: async (req, res) => {
if (req.context.eventName === "message") {
console.log(`Received message: ${req.data}`);
// Additional logic to process the data,
// e.g save message content to database
// or broadcast the message to selected clients.
}
},
});
//... code from before
클라이언트 프로그램 및 서버 프로그램 다시 시작
콘솔에 userId 및 Received message: sending custom event!가 출력된 것을 볼 수 있습니다.
요약
이 자습서에서는 Web PubSub에서 이벤트 시스템이 작동하는 방식에 대한 기본 개념을 제공합니다. 실제 애플리케이션에서 이벤트 시스템은 시스템 및 사용자 생성 이벤트를 처리하기 위한 더 많은 논리를 구현하는 데 도움이 될 수 있습니다.