JavaScript용 Web PubSub 클라이언트 라이브러리

  • 아티클

Azure Web PubSub 는 개발자가 대규모로 게시-구독 패턴을 사용하여 웹 애플리케이션에서 실시간 기능을 쉽게 빌드할 수 있도록 도와주는 클라우드 서비스입니다.

서버와 클라이언트 간 또는 게시-구독 패턴을 따르는 클라이언트 간에 실시간 메시징이 필요한 시나리오는 Web PubSub를 사용하면 이점을 얻을 수 있습니다. 개발자는 더 이상 반복된 HTTP 요청을 간격으로 전송하여 서버를 폴링할 필요가 없습니다. 이는 낭비되고 크기가 어렵습니다.

아래 다이어그램에 표시된 것처럼 클라이언트는 Web PubSub 리소스와 WebSocket 연결을 설정합니다. 이 클라이언트 라이브러리:

  • 클라이언트 연결 관리 간소화
  • 클라이언트 간에 메시지 보내기 간소화
  • 의도하지 않은 클라이언트 연결 삭제 후 자동으로 다시 시도
  • 연결 끊기에서 복구한 후 수와 순서대로 메시지를 안정적으로 배달합니다.

오버플로

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

이 라이브러리는 NPM에서 호스트됩니다.

시작

현재 지원되는 환경

필수 구성 요소

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

npm install @azure/web-pubsub-client

2. Web PubSub 리소스로 연결

클라이언트는 클라이언트 액세스 URL을 사용하여 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>의 패턴을 따르는 서비스에 연결하고 인증합니다. 클라이언트는 클라이언트 액세스 URL을 가져오는 몇 가지 방법을 사용할 수 있습니다. 이 빠른 시작을 위해 아래 표시된 Azure Portal에서 복사하여 붙여넣을 수 있습니다. (프로덕션의 경우 클라이언트는 일반적으로 애플리케이션 서버에서 클라이언트 액세스 URL을 계보화합니다. 아래 세부 정보를 참조하세요 .

get_client_url

위의 다이어그램에 표시된 것처럼 클라이언트에는 메시지를 보내고 "group1"이라는 특정 그룹에 가입할 수 있는 권한이 있습니다.

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. 그룹 조인

클라이언트는 조인된 그룹에서만 메시지를 받을 수 있으며 메시지를 받을 때 논리를 지정하는 콜백을 추가해야 합니다.

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. 그룹에 메시지 보내기

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

예제

연결, 연결 끊김 및 중지된 이벤트에 대한 콜백 추가

  1. 클라이언트가 Web PubSub 리소스 connected 에 성공적으로 연결되면 이벤트가 트리거됩니다.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. 클라이언트의 연결이 끊어지고 연결을 disconnected 복구하지 못하면 이벤트가 트리거됩니다.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. 클라이언트의 연결이 끊어지고 클라이언트가 다시 연결 시도를 중지하면 이벤트가 트리거됩니다.stopped 이는 일반적으로 가 client.stop() 호출되거나 사용하지 않도록 설정되거나 autoReconnect 다시 연결하려고 하는 지정된 제한에 도달한 후에 발생합니다. 클라이언트를 다시 시작하려면 중지된 이벤트에서 를 호출 client.start() 할 수 있습니다.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

협상 서버를 사용하여 프로그래밍 방식으로 클라이언트 액세스 URL 생성

프로덕션에서 클라이언트는 일반적으로 애플리케이션 서버에서 클라이언트 액세스 URL을 가져옵니다. 서버는 Web PubSub 리소스에 대한 연결 문자열 보유하고 서버 라이브러리 @azure/web-pubsub의 도움을 받아 클라이언트 액세스 URL을 생성합니다.

1. 애플리케이션 서버

아래 코드 조각은 애플리케이션 서버가 경로를 노출하고 클라이언트 액세스 URL을 /negotiate 반환하는 예제입니다.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. 클라이언트 쪽

아래 코드 조각은 클라이언트 쪽의 예입니다.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

이 샘플의 전체 코드를 보려면 samples-browser를 참조하세요.

클라이언트가 애플리케이션 서버 또는 조인된 그룹의 메시지를 사용합니다.

클라이언트는 콜백을 추가하여 애플리케이션 서버 또는 그룹의 메시지를 사용할 수 있습니다. 이벤트의 경우 group-message 클라이언트는 조인한 그룹 메시지 만 받을 수 있습니다.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

다시 가입 실패 처리

클라이언트의 연결이 끊어지고 복구에 실패하면 Web PubSub 리소스에서 모든 그룹 컨텍스트가 정리됩니다. 즉, 클라이언트가 다시 연결되면 그룹에 다시 가입해야 합니다. 기본적으로 클라이언트에는 autoRejoinGroup 옵션이 활성화되어 있습니다.

그러나 의 제한 사항을 알고 autoRejoinGroup있어야 합니다.

  • 클라이언트는 원래 서버 쪽 코드가 아닌 클라이언트 코드에 의해 조인된 그룹만 다시 조인할 수 있습니다.
  • "그룹 다시 가입" 작업은 여러 가지 이유로 인해 실패할 수 있습니다( 예: 클라이언트에 그룹에 조인할 수 있는 권한이 없음). 이러한 경우 이 오류를 처리하기 위해 콜백을 추가해야 합니다.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

작업 및 다시 시도

기본적으로 , , client.leaveGroup()등의 client.joinGroup()client.sendToGroup()client.sendEvent() 작업에는 세 번의 재시도가 있습니다. 를 통해 messageRetryOptions구성할 수 있습니다. 모든 재시도에 실패하면 오류가 throw됩니다. Web PubSub 서비스가 작업을 중복 제거할 수 있도록 이전 재시도와 동일한 ackId 를 전달하여 재시도를 계속할 수 있습니다.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

하위 프로젝트 지정

클라이언트에서 사용할 하위 프로토콜을 변경할 수 있습니다. 기본적으로 클라이언트는 를 사용합니다 json.reliable.webpubsub.azure.v1. 또는 json.webpubsub.azure.v1을 사용하도록 json.reliable.webpubsub.azure.v1 선택할 수 있습니다.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

주요 개념

연결

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

복구

신뢰할 수 있는 프로토콜을 사용하는 클라이언트의 연결이 끊어지면 새 WebSocket이 연결 끊김의 연결 ID를 사용하여 설정을 시도합니다. 새 WebSocket 연결이 성공적으로 연결되면 연결이 복구됩니다. 클라이언트의 연결이 끊기는 동안 서비스는 클라이언트의 컨텍스트와 클라이언트가 구독한 모든 메시지를 유지하고 클라이언트가 복구되면 서비스에서 이러한 메시지를 클라이언트로 보냅니다. 서비스에서 WebSocket 오류 코드를 1008 반환하거나 복구 시도가 30초 이상 지속되면 복구가 실패합니다.

다시 연결

다시 연결은 클라이언트 연결이 끊어지고 복구에 실패할 때 발생합니다. 다시 연결은 새 연결을 시작하고 새 연결에 새 연결 ID가 있습니다. 복구와 달리 서비스는 다시 연결된 클라이언트를 새 클라이언트 연결로 처리합니다. 클라이언트 연결은 그룹에 다시 가입해야 합니다. 기본적으로 클라이언트 라이브러리는 다시 연결한 후 그룹에 다시 참가합니다.

허브

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

그룹화

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

사용자

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

클라이언트 수명

각 Web PubSub 클라이언트는 애플리케이션 수명 동안 캐시하고 싱글톤으로 사용할 수 있습니다. 등록된 이벤트 콜백은 클라이언트와 동일한 수명을 공유합니다. 즉, 언제든지 콜백을 추가하거나 제거할 수 있으며 다시 연결하거나 클라이언트가 중지된 후 등록 상태 변경되지 않습니다.

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

문제 해결

  • 로그 사용 설정

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

export AZURE_LOG_LEVEL=verbose

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

추가 리소스

참여

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