Java용 Azure WebPubSub 클라이언트 라이브러리

참고 항목

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

클라이언트 쪽 SDK는 개발자의 워크플로 속도를 높이는 것을 목표로 합니다. 보다 구체적으로 말하면 다음과 같습니다.

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

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

Web PubSub 리소스를 사용하여 WebSocket 연결을 설정하는 클라이언트를 보여 주는 스크린샷

Important

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다.

연결 문자열에는 애플리케이션이 Azure Web PubSub 서비스에 액세스하는 데 필요한 권한 부여 정보가 포함됩니다. 연결 문자열 내의 액세스 키는 서비스의 루트 암호와 비슷합니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 연결을 WebPubSubServiceClient보호합니다.

액세스 키를 다른 사용자에게 배포하거나 하드 코딩하거나 다른 사용자가 액세스할 수 있는 일반 텍스트로 저장하지 않도록 합니다. 키가 손상되었다고 생각되면 키를 교체하세요.

시작

필수 조건

  • 버전 8 이상이 있는 JDK(Java Development Kit)
  • Azure 구독
  • 기존 Web PubSub 인스턴스

제품에 패키지 추가

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub-client</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

클라이언트 인증

클라이언트는 Client Access URL을 사용하여 서비스에 연결하고 인증합니다. URL은 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> 패턴을 따릅니다. Client Access URL을 가져오는 방법에는 여러 가지가 있습니다. 빠른 시작으로 Azure Portal에서 복사하여 붙여넣을 수 있으며, 프로덕션의 경우 일반적으로 URL을 생성하기 위해 협상 서버가 필요합니다. 세부 정보를 참조하세요.

Azure Portal에서 Client Access URL 사용

빠른 시작으로 Azure Portal로 이동하여 키 블레이드에서 클라이언트 액세스 URL을 복사할 수 있습니다.

Azure Portal에서 클라이언트 액세스 URL을 가져오는 방법을 보여 주는 스크린샷

다이어그램에 표시된 것처럼 클라이언트에는 특정 그룹에 메시지를 보내고 특정 그룹에 조인할 수 있는 권한이 부여됩니다. 클라이언트 권한에 대한 자세한 내용은 권한을 참조하세요.

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

협상 서버를 사용하여 Client Access URL 생성

프로덕션 환경에서 클라이언트는 일반적으로 협상 서버에서 Client Access URL을 가져옵니다. 서버는 connection string을 보유하고 Client Access URL를 통해 WebPubSubServiceClient을 생성합니다. 샘플로 제공되는 이 코드 조각은 단일 프로세스 내에서 Client Access URL을 생성하는 방법을 보여 줍니다.

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 연결을 WebPubSubServiceClient보호합니다.

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

WebPubSubClient와 WebPubSubServiceClient를 구분하는 기능입니다.

클래스 이름 WebPubSubClient WebPubSubServiceClient
패키지 이름 azure-messaging-webpubsub-client azure-messaging-webpubsub
기능 클라이언트 쪽에서 사용됩니다. 메시지를 게시하고 메시지를 구독합니다. 서버 쪽에서 사용됩니다. Client Access URL을 생성하고 클라이언트를 관리합니다.

예제

서버 및 그룹의 메시지 사용

클라이언트는 콜백을 추가하여 서버 및 그룹의 메시지를 사용할 수 있습니다. 클라이언트는 조인된 그룹 메시지만 받을 수 있습니다.

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

connected, disconnected 및 stopped 이벤트에 대한 콜백 추가

클라이언트 연결이 서비스에 연결되면 connected 이벤트가 트리거됩니다.

클라이언트 연결이 끊어지고 복구에 실패하면 disconnected 이벤트가 트리거됩니다.

클라이언트가 중지되면 클라이언트 연결이 끊어지고 클라이언트가 다시 연결하려는 시도를 중지하면 stopped 이벤트가 트리거됩니다. 일반적으로 client.StopAsync()가 호출되거나 AutoReconnect가 사용하지 않도록 설정된 후에 발생합니다. 클라이언트를 다시 시작하려는 경우 client.StartAsync() 이벤트에서 Stopped를 호출할 수 있습니다.

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

작업 및 다시 시도

기본적으로 client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() 등의 작업은 3번 다시 시도됩니다. WebPubSubClientBuilder.retryOptions()를 사용하여 변경할 수 있습니다. 모든 다시 시도가 실패하면 오류가 throw됩니다. 이전 재시도와 동일한 ackId를 전달하여 계속 재시도할 수 있으므로 서비스는 동일한 ackId를 사용하여 작업을 중복 제거하도록 도울 수 있습니다.

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

문제 해결

로그 사용 설정

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

export AZURE_LOG_LEVEL=verbose

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

라이브 추적

Azure Portal의 라이브 추적 도구를 사용하여 Web PubSub 리소스를 통해 라이브 메시지 트래픽을 검사합니다.

  • Last updated on