Azure Web PubSub에 대한 WebSocket 클라이언트 프로토콜
클라이언트는 표준 WebSocket 프로토콜을 사용하여 Azure Web PubSub에 연결합니다.
서비스 엔드포인트
Web PubSub 서비스는 클라이언트가 연결할 두 가지 형식의 엔드포인트를 제공합니다.
/client/hubs/{hub}/client/?hub={hub}
{hub}는 다양한 애플리케이션에 대한 격리 역할을 하는 필수 매개 변수입니다. 경로 또는 쿼리에서 설정할 수 있습니다.
Authorization
클라이언트는 JWT(JSON Web Token)를 사용하여 서비스에 연결합니다. 토큰은 쿼리 문자열(/client/?hub={hub}&access_token={token}) 또는 Authorization 헤더(Authorization: Bearer {token})에 있을 수 있습니다.
일반적인 권한 부여 워크플로는 다음과 같습니다.
- 클라이언트는 애플리케이션 서버와 협상합니다. 애플리케이션 서버에는 클라이언트 요청을 처리하고 클라이언트가 서비스에 연결할 수 있도록 JWT에 서명하는 권한 부여 미들웨어가 포함되어 있습니다.
- 애플리케이션 서버는 JWT 및 서비스 URL을 클라이언트에 반환합니다.
- 클라이언트는 애플리케이션 서버에서 반환된 URL 및 JWT 토큰을 사용하여 Web PubSub 서비스에 연결하려고 합니다.
지원되는 클레임
JWT 토큰 내에서 특수 클레임을 지정하여 액세스 토큰을 생성할 때 클라이언트 연결에 대한 속성을 구성할 수도 있습니다.
| 설명 | 클레임 유형 | 클레임 값 | 주의 |
|---|---|---|---|
userId 클라이언트 연결의 경우 |
sub |
userId | 하나의 sub 클레임만 허용됩니다. |
| 토큰의 수명 | exp |
만료 시간 | (만료 시간) 클레임은 exp 토큰 처리를 위해 토큰을 수락해서는 안 되는 만료 시간을 식별합니다. |
| 클라이언트 연결이 처음에 가지고 있는 사용 권한 | role |
권한에 정의된 역할 값 | 클라이언트에 여러 role 권한이 있는 경우 여러 클레임을 지정합니다. |
| 클라이언트 연결이 Azure Web PubSub에 연결되면 조인하는 초기 그룹 | group |
조인할 그룹 | 클라이언트가 여러 group 그룹에 조인하는 경우 여러 클레임을 지정합니다. |
액세스 토큰에 사용자 지정 클레임을 추가할 수도 있으며, 이러한 값은 연결 업스트림 요청 본문의 속성으로 claims 유지됩니다.
서버 SDK는 클라이언트에 대한 액세스 토큰을 생성하는 API를 제공합니다.
단순 WebSocket 클라이언트
이름에서 알 수 있듯이 간단한 WebSocket 클라이언트는 단순 WebSocket 연결입니다. 자체 사용자 지정 하위 프로토콜을 가질 수도 있습니다.
예를 들어, JavaScript에서 다음 코드를 사용하여 간단한 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')
PubSub WebSocket 클라이언트
PubSub WebSocket 클라이언트는 Azure Web PubSub 서비스에서 정의한 하위 프로토콜을 사용하는 WebSocket 클라이언트입니다.
json.webpubsub.azure.v1protobuf.webpubsub.azure.v1
서비스 지원 하위 프로토콜을 사용하면 PubSub WebSocket 클라이언트는 권한이 있는 그룹에 메시지를 직접 게시할 수 있습니다.
json.webpubsub.azure.v1 하위 프로토콜
JSON 하위 프로토콜에 대한 자세한 내용은 여기를 확인합니다.
PubSub WebSocket 클라이언트 만들기
var pubsubClient = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
클라이언트에서 직접 그룹에 조인
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'joinGroup',
group: 'group1',
ackId: ++ackId
}));
클라이언트에서 그룹으로 직접 메시지 보내기
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'sendToGroup',
group: 'group1',
ackId: ++ackId,
dataType: "json",
data: {
"hello": "world"
}
}));
protobuf.webpubsub.azure.v1 하위 프로토콜
protobuf(프로토콜 버퍼)는 이진 파일 데이터 전송을 단순화하는 언어 중립적, 플랫폼 중립적, 이진 파일 기반 프로토콜입니다. protobuf는 Java, Python, Objective-C, C# 및 C++와 같은 여러 언어에 대한 클라이언트를 생성하는 도구를 제공합니다. protobuf에 대해 자세히 알아봅니다.
예를 들어, JavaScript에서 다음 코드를 사용하여 protobuf 하위 프로토콜로 PubSub WebSocket 클라이언트를 만들 수 있습니다.
// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.webpubsub.azure.v1');
protobuf 하위 프로토콜에 대한 자세한 내용은 여기를 확인합니다.
AckId 및 Ack 응답
PubSub WebSocket 클라이언트는 joinGroup, leaveGroup, sendToGroup 및 event 메시지에 대한 ackId 속성을 지원합니다. ackId를 사용하면 요청이 처리될 때 ack 응답 메시지를 받을 수 있습니다. 실행 후 제거 시나리오에서 ackId를 생략하도록 선택할 수 있습니다. 이 문서에서는 ackId 지정 여부의 동작 차이를 설명합니다.
ackId가 지정되지 않은 경우의 동작
지정되지 않은 경우 ackId fire-and-forget입니다. 메시지를 중개할 때 오류가 발생하더라도 알림을 받을 방법이 없습니다.
ackId가 지정된 경우 동작
Idempotent 게시
ackId 는 uint64 숫자이며 연결 ID가 동일한 클라이언트 내에서 고유해야 합니다. Web PubSub 서비스는 동일한 메시지를 기록하고 ackId 메시지는 동일한 ackId 메시지로 처리됩니다. 서비스는 동일한 메시지를 두 번 이상 중개하는 것을 거부하므로 메시지 중복을 피하기 위해 다시 시도할 때 유용합니다. 예를 들어, 클라이언트가 ackId=5로 메시지를 보내고 ackId=5로 ack 응답을 받지 못한 경우 클라이언트는 다시 시도하고 동일한 메시지를 다시 보냅니다. 경우에 따라 메시지가 이미 조정되었으며 어떤 이유로 인해 ack 응답이 손실됩니다. 서비스는 재시도를 거부하고 이유와 함께 Duplicate ack 응답을 응답합니다.
Ack 응답
Web PubSub 서비스는 ackId로 각 요청에 대한 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>"
}
}
ackId는 요청을 연결합니다.success는 부울이며 요청이 서비스에서 성공적으로 처리되었는지 여부를 나타냅니다.false이 경우 클라이언트는 검사 합니다error.error는success가false이고 클라이언트가 다른name에 대해 다른 논리를 가져야 하는 경우에만 존재합니다. 앞으로 더 많은 형식의name이 있을 수 있다고 가정해야 합니다.Forbidden: 클라이언트에 요청에 대한 권한이 없습니다. 클라이언트에 관련 역할을 추가해야 합니다.InternalServerError: 서비스에서 일부 내부 오류가 발생했습니다. 다시 시도해야 합니다.Duplicate:ackId가 같은 메시지가 서비스에서 이미 처리되었습니다.
사용 권한
이전 PubSub WebSocket 클라이언트 설명에서 알 수 있듯이 클라이언트는 승인된 경우에만 다른 클라이언트에 게시할 수 있습니다. 연결 중이거나 연결이 지속되는 동안 클라이언트의 권한을 부여할 수 있습니다.
| 역할 | Permission |
|---|---|
| 지정되지 않음 | 클라이언트는 이벤트 요청을 보낼 수 있습니다. |
webpubsub.joinLeaveGroup |
클라이언트는 모든 그룹에 조인하거나 탈퇴할 수 있습니다. |
webpubsub.sendToGroup |
클라이언트는 모든 그룹에 메시지를 게시할 수 있습니다. |
webpubsub.joinLeaveGroup.<group> |
클라이언트는 <group> 그룹에 조인하거나 탈퇴할 수 있습니다. |
webpubsub.sendToGroup.<group> |
클라이언트는 <group> 그룹에 메시지를 게시할 수 있습니다. |
클라이언트의 권한은 여러 가지 방법으로 부여될 수 있습니다.
1. 액세스 토큰 생성 시 클라이언트에 역할 할당
클라이언트는 JWT 토큰을 사용하여 서비스에 연결할 수 있습니다. 토큰 페이로드는 클라이언트와 같은 role 정보를 전달할 수 있습니다. JWT 토큰을 클라이언트에 서명할 때 클라이언트에 특정 역할을 부여하여 클라이언트에 권한을 부여할 수 있습니다.
예를 들어, group1 및 group2에 메시지를 보낼 수 있는 권한이 있는 JWT 토큰에 서명해 보겠습니다.
let token = await serviceClient.getClientAccessToken({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
2. connect 이벤트 처리기를 사용하여 클라이언트에 역할 할당
클라이언트의 역할도 connect 이벤트 처리기 등록 시 설정할 수 있으며, 업스트림 이벤트 처리기는 connect 이벤트 처리 시 클라이언트의 roles를 Web PubSub 서비스로 반환할 수 있습니다.
예를 들어, JavaScript에서 다음과 같이 handleConnect 이벤트를 구성할 수 있습니다.
let handler = new WebPubSubEventHandler("hub1", {
handleConnect: (req, res) => {
// auth the connection and set the userId of the connection
res.success({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
},
});
3. 런타임 중에 REST API 또는 서버 SDK를 통해 클라이언트에 역할 할당
let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });
다음 단계
다음 리소스를 사용하여 사용자 고유의 애플리케이션 빌드를 시작합니다.