Клиентская библиотека Azure WebPubSub для Java

Примечание.

Сведения об терминах, используемых здесь, описаны в статье основных понятий.

Клиентский пакет SDK направлен на ускорение рабочего процесса разработчика; в частности,

• упрощение управления клиентскими подключениями
• упрощение отправки сообщений среди клиентов
• автоматически повторяется после непреднамеренного удаления подключения клиента
• надежно доставка сообщений в количестве и порядке после восстановления после удаления подключений

Как показано на схеме, клиенты устанавливают подключения WebSocket к ресурсу Web PubSub.

Внимание

Необработанные строка подключения отображаются в этой статье только для демонстрационных целей.

Строка подключения содержит сведения об авторизации, требуемые для доступа приложения к службе Azure Web PubSub. Ключ доступа в строке подключения аналогичен паролю привилегированного пользователя для службы. В рабочих средах всегда защищать ключи доступа. Используйте Azure Key Vault для безопасного управления ключами и защиты подключения.WebPubSubServiceClient

Старайтесь не распространять ключи доступа среди других пользователей, жестко программировать их или где-то сохранять в виде обычного текста в открытом доступе для других пользователей. Меняйте свои ключи постоянно, если предполагаете, что они могут быть подобраны.

Начало работы

Необходимые компоненты

• Пакет разработчиков Java (JDK) версии 8 или более поздней.
• Подписка 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, а для рабочей среды обычно требуется сервер переговоров для создания URL-адреса. Подробнее.

Использование Client Access URL из портал Azure

В качестве краткого руководства вы можете перейти к портал Azure и скопировать URL-адрес клиентского доступа из колонки "Ключи".

Как показано на схеме, клиент получает разрешение на отправку сообщений определенным группам и присоединение к определенным группам. Дополнительные сведения о разрешении клиента см. в разделе "Разрешения".

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

Создание сервера переговоров Client Access URL

В рабочей среде клиент обычно извлекает Client Access URL сервер переговоров. Сервер содержит connection string и создает его Client Access URLWebPubSubServiceClient. В качестве примера фрагмент кода просто демонстрирует, как создать 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() имеет три повтора. Вы можете использовать WebPubSubClientBuilder.retryOptions() для изменения. Если произошел сбой всех повторных попыток, возникает ошибка. Повторите попытку, передав ту же ackId , что и предыдущие повторные попытки, поэтому служба может помочь дедупликации операции с той же ackId.

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

Устранение неполадок

Включение журналов

При использовании этой библиотеки с помощью приведенной ниже переменной среды можно получить журналы отладки.

export AZURE_LOG_LEVEL=verbose

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Динамическая трассировка

Используйте средство динамической трассировки из портал Azure для проверки трафика сообщений через ресурс Web PubSub.