Учебник. Создание чат-приложения с помощью службы Azure Web PubSub

В руководстве по публикации и подписке на сообщения вы узнаете, как публиковать и подписывать сообщения с помощью Azure Web PubSub. В этом руководстве описана система событий Azure Web PubSub и ее использование для создания полного веб-приложения с функциями взаимодействия в режиме реального времени.

В этом руководстве описано следующее:

• Создание экземпляра службы Web PubSub.
• настроить параметры обработчика событий для Azure Web PubSub;
• События Hanlde на сервере приложений и создание приложения чата в режиме реального времени

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

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

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

• Для работы с этим руководством требуется Azure CLI версии 2.22.0 или выше. Если вы используете Azure Cloud Shell, последняя версия уже установлена.

Создание экземпляра Azure Web PubSub

Создание или изменение группы ресурсов

Группа ресурсов — это логический контейнер, в котором происходит развертывание ресурсов Azure и управление ими. Используйте команду az group create, чтобы создать группу ресурсов с именем myResourceGroup в расположенииeastus.

az group create --name myResourceGroup --location EastUS

Создание экземпляра Web PubSub

Запустите az extension add to install or upgrade the webpubsub extension to the current version.

az extension add --upgrade --name webpubsub

Используйте команду azure CLI az webpubsub create , чтобы создать web PubSub в созданной группе ресурсов. Следующая команда создает ресурс Free Web PubSub в группе ресурсов myResourceGroup в EastUS:

Внимание

Каждый ресурс Web PubSub должен иметь уникальное имя. В следующих примерах замените <your-unique-resource-name> именем своей службы Web PubSub.

az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1

В выходных данных команды будут показаны свойства созданного ресурса. Запишите значения двух указанных ниже свойств.

• Имя ресурса: имя, которое вы ввели для указанного выше параметра --name.
• hostName: в примере имя узла <your-unique-resource-name>.webpubsub.azure.com/.

На данном этапе любые операции в этом новом ресурсе могут выполняться только с использованием вашей учетной записи Azure.

Получение ConnectionString для будущего использования

Внимание

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

Выполните команду Azure CLI az webpubsub key, чтобы получить значение ConnectionString службы. Замените <your-unique-resource-name> заполнитель именем экземпляра Azure Web PubSub.

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

Скопируйте строка подключения для последующего использования.

Скопируйте извлекаемый Подключение ionString и задайте его в переменную WebPubSubConnectionStringсреды, которую учебник позже читает. Замените <connection-string> приведенный ниже элементом Подключение ionString, который вы извлекли.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Настройка проекта

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

C#

• ASP.NET Core 8

JavaScript

• Node.js 12.x или более поздней версии

Java

• Комплект SDK для Java (JDK) версии 8 или более поздней версии.
• Apache Maven

Python

• python 3.8 или более поздней версии

Создание приложения

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

В этом руководстве мы создадим веб-приложение чата в режиме реального времени. В реальном веб-приложении сервер также отвечает за проверку подлинности клиентов и предоставление статических веб-страниц для пользовательского интерфейса приложения.

C#

Мы используем ASP.NET Core 8 для размещения веб-страниц и обработки входящих запросов.

Сначала создадим веб-приложение ASP.NET Core в папке chatapp .

1. Создание веб-приложения.

   mkdir chatapp
   cd chatapp
   dotnet new web
   

2. Добавьте app.UseStaticFiles() Program.cs для поддержки размещения статических веб-страниц.

   var builder = WebApplication.CreateBuilder(args);
   var app = builder.Build();
   
   app.UseStaticFiles();
   
   app.Run();
   

3. Создайте HTML-файл и сохраните его как wwwroot/index.html, мы используем его для пользовательского интерфейса приложения чата позже.

   <html>
     <body>
       <h1>Azure Web PubSub Chat</h1>
     </body>
   </html>
   

Вы можете протестировать сервер, запустив dotnet run --urls http://localhost:8080 и доступ http://localhost:8080/index.html в браузере.

JavaScript

Мы используем express.js, популярную веб-платформу для Node.js для размещения веб-страниц и обработки входящих запросов.

Сначала создадим экспресс-веб-приложение в папке chatapp .

1. Установка express.js

   mkdir chatapp
   cd chatapp
   npm init -y
   npm install --save express
   

2. Затем создайте сервер express и сохраните его как server.js.

   const express = require('express');
   
   const app = express();
   app.use(express.static('public'));
   app.listen(8080, () => console.log('server started'));
   

3. Кроме того, создайте HTML-файл и сохраните его как public/index.html, мы используем его для пользовательского интерфейса приложения чата позже.

   <html>
   
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Вы можете протестировать сервер, запустив node server и доступ http://localhost:8080 в браузере.

Java

Мы используем веб-платформу Javalin для размещения веб-страниц и обработки входящих запросов.

1. Используйте Maven для создания нового приложения webpubsub-tutorial-chat и переключения в папку webpubsub-tutorial-chat :

   mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.tutorial --define artifactId=webpubsub-tutorial-chat --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
   cd webpubsub-tutorial-chat
   

2. javalin Добавьте зависимость веб-платформы dependencies в узелpom.xml:

   • javalin — простая веб-платформа для Java
   • slf4j-simple — средство ведения журнала для Java

   <!-- https://mvnrepository.com/artifact/io.javalin/javalin -->
   <dependency>
       <groupId>io.javalin</groupId>
       <artifactId>javalin</artifactId>
       <version>6.1.3</version>
   </dependency>
   
   <!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-simple -->
   <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-simple</artifactId>
       <version>2.0.12</version>
   </dependency>
   

3. Перейдите в каталог /src/main/java/com/webpubsub/tutorial . Откройте файл App.java в редакторе. Используется Javalin.create для обслуживания статических файлов:

   package com.webpubsub.tutorial;
   
   import io.javalin.Javalin;
   
   public class App {
       public static void main(String[] args) {
           // start a server
           Javalin app = Javalin.create(config -> {
               config.staticFiles.add("public");
           }).start(8080);
       }
   }
   

   В зависимости от настроек может потребоваться явно задать уровень языка Java 8. Этот шаг можно выполнить в pom.xml. Добавьте следующий фрагмент кода:

   <build>
       <plugins>
           <plugin>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.8.0</version>
             <configuration>
               <source>1.8</source>
               <target>1.8</target>
             </configuration>
           </plugin>
       </plugins>
   </build>
   

4. Создайте HTML-файл и сохраните его в /src/main/resources/public/index.html. Мы используем его для пользовательского интерфейса приложения чата позже.

   <html>
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Вы можете протестировать сервер, выполнив следующую команду в каталоге, содержащем файл pom.xml, и перейдя в браузере по адресу http://localhost:8080.

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Python

Мы используем Flask, популярную веб-платформу для Python для достижения этой задачи.

Сначала создайте папку chatapp проекта с готовым Flask.

0. Создание и активация среды

   mkdir chatapp
   cd chatapp
   python3 -m venv .venv
   . .venv/bin/activate
   

1. В активированной среде установите Flask

   pip install Flask
   

2. Затем создайте сервер Flask и сохраните его как server.py

   from flask import (
       Flask, 
       send_from_directory,
   )
   
   app = Flask(__name__)
   
   @app.route('/<path:filename>')
   def index(filename):
       return send_from_directory('public', filename)
   
   if __name__ == '__main__':
       app.run(port=8080)
   

3. Кроме того, создайте HTML-файл и сохраните его как public/index.html, мы используем его для пользовательского интерфейса приложения чата позже.

   <html>
   
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Чтобы протестировать сервер, выполните команду python server.py и перейдите в браузере по адресу http://127.0.0.1:8080/index.html.

Добавление конечной точки согласования

В руководстве по публикации и подписке подписчик использует строка подключения напрямую. В реальном мире приложение не безопасно совместно использовать строка подключения с любым клиентом, так как строка подключения имеет высокий уровень привилегий для выполнения любой операции со службой. Теперь давайте будем использовать строка подключения сервера и предоставлять конечную negotiate точку для клиента, чтобы получить полный URL-адрес с маркером доступа. Таким образом, сервер может добавить ПО промежуточного слоя проверки подлинности перед конечной negotiate точкой, чтобы предотвратить несанкционированный доступ.

C#

Сначала установите зависимости.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Теперь добавим конечную /negotiate точку для вызова клиента для создания маркера.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() используется для внедрения клиента WebPubSubServiceClient<THub>службы, с помощью которого мы можем использовать в шаге согласования для создания маркера подключения клиента и в методах концентратора для вызова ИНТЕРФЕЙСов REST API службы при активации событий концентратора. Этот код создания маркера аналогичен тому, который мы использовали в учебнике по публикации сообщения и подписке на него, за исключением того, что передается еще один аргумент (userId). Идентификатор пользователя можно использовать для идентификации клиента, так что при получении сообщения вы знаете, откуда оно поступило.

Код считывает строка подключения из переменной WebPubSubConnectionString среды, заданной на предыдущем шаге.

Повторное выполнение сервера с помощью dotnet run --urls http://localhost:8080.

JavaScript

Сначала установите пакет SDK для Azure Web PubSub:

npm install --save @azure/web-pubsub

Теперь добавим /negotiate API для создания маркера.

const express = require('express');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

const app = express();
const hubName = 'Sample_ChatApp';

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

app.get('/negotiate', async (req, res) => {
    let id = req.query.id;
    if (!id) {
    res.status(400).send('missing user id');
    return;
    }
    let token = await serviceClient.getClientAccessToken({ userId: id });
    res.json({
    url: token.url
    });
});

app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Этот код создания маркера аналогичен тому, который мы использовали в учебнике по публикации сообщения и подписке на него, за исключением того, что передается еще один аргумент (userId). Идентификатор пользователя можно использовать для идентификации клиента, так что при получении сообщения вы знаете, откуда оно поступило.

Код считывает строка подключения из переменной WebPubSubConnectionString среды, заданной на предыдущем шаге.

Повторное выполнение сервера путем запуска node server.

Java

Сначала добавьте зависимость пакета SDK для Azure Web PubSub и gson в dependencies узел pom.xml:

<!-- https://mvnrepository.com/artifact/com.azure/azure-messaging-webpubsub -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.2.12</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Теперь давайте добавим /negotiate API в App.java файл для создания маркера:

package com.webpubsub.tutorial;
    
import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
import com.azure.messaging.webpubsub.models.WebPubSubContentType;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        String connectionString = System.getenv("WebPubSubConnectionString");

        if (connectionString == null) {
            System.out.println("Please set the environment variable WebPubSubConnectionString");
            return;
        }

        // create the service client
        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
                .connectionString(connectionString)
                .hub("Sample_ChatApp")
                .buildClient();

        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
        
        // Handle the negotiate request and return the token to the client
        app.get("/negotiate", ctx -> {
            String id = ctx.queryParam("id");
            if (id == null) {
                ctx.status(400);
                ctx.result("missing user id");
                return;
            }
            GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
            option.setUserId(id);
            WebPubSubClientAccessToken token = service.getClientAccessToken(option);
            ctx.contentType("application/json");
            Gson gson = new Gson();
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("url", token.getUrl());
            String response = gson.toJson(jsonObject);
            ctx.result(response);
            return;
        });
    }
}

Этот код создания маркера аналогичен тому, который мы использовали в учебнике по публикации сообщения и подписке на него, за исключением того, что мы вызываем метод setUserId для задания идентификатора пользователя при создании маркера. Идентификатор пользователя можно использовать для идентификации клиента, так что при получении сообщения вы знаете, откуда оно поступило.

Код считывает строка подключения из переменной WebPubSubConnectionString среды, заданной на предыдущем шаге.

Повторно запустите сервер с помощью следующих команд:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Python

Сначала установите пакет SDK для Azure Web PubSub.

pip install azure-messaging-webpubsubservice

Теперь добавим /negotiate API на сервер для создания маркера.

import os

from flask import (
    Flask, 
    request, 
    send_from_directory,
)

from azure.messaging.webpubsubservice import (
    WebPubSubServiceClient
)

hub_name = 'Sample_ChatApp'
connection_string = os.environ.get('WebPubSubConnectionString')

app = Flask(__name__)
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)


@app.route('/negotiate')
def negotiate():
    id = request.args.get('id')
    if not id:
        return 'missing user id', 400

    token = service.get_client_access_token(user_id=id)
    return {
        'url': token['url']
    }, 200

if __name__ == '__main__':
    app.run(port=8080)

Этот код создания маркера аналогичен тому, который мы использовали в учебнике по публикации сообщения и подписке на него, за исключением того, что передается еще один аргумент (user_id). Идентификатор пользователя можно использовать для идентификации клиента, так что при получении сообщения вы знаете, откуда оно поступило.

Код считывает строка подключения из переменной WebPubSubConnectionString среды, заданной на предыдущем шаге.

Повторное выполнение сервера с помощью python server.py.

Вы можете протестировать этот API, выполнив доступ http://localhost:8080/negotiate?id=user1 и предоставив полный URL-адрес веб-pubSub Azure с маркером доступа.

Обработка событий

В Azure Web PubSub, когда на стороне клиента происходят определенные действия (например, клиент подключается, подключен, отключен или клиент отправляет сообщения), служба отправляет уведомления на сервер, чтобы реагировать на эти события.

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

Описание данных событий в Azure Web PubSub соответствует спецификации CloudEvents.

Ниже мы обрабатываем connected системные события, когда клиент подключен и обрабатывает message события пользователя, когда клиент отправляет сообщения для создания приложения чата.

C#

Пакет SDK Web PubSub для AspNetCore Microsoft.Azure.WebPubSub.AspNetCore , установленный на предыдущем шаге, также может помочь проанализировать и обработать запросы CloudEvents.

Сначала добавьте обработчики событий.app.Run() Укажите путь к конечной точке для событий, допустим /eventhandler.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

Теперь внутри класса Sample_ChatApp , созданного на предыдущем шаге, добавьте конструктор для работы со WebPubSubServiceClient<Sample_ChatApp> службой Web PubSub. И OnConnectedAsync() реагировать на события при connected активации события для OnMessageReceivedAsync() обработки сообщений от клиента.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

В приведенном выше коде мы используем клиент службы для трансляции сообщения уведомления в формате JSON, с которым присоединяется SendToAllAsyncвсе.

JavaScript

Пакет SDK Web PubSub для Express @azure/web-pubsub-express помогает анализировать запросы CloudEvents и обрабатывать их.

npm install --save @azure/web-pubsub-express

Обновите server.js со следующим кодом, чтобы предоставить REST API /eventhandler (который выполняется по промежуточному по промежуточному слоям, предоставляемым пакетом SDK web PubSub), для обработки события, подключенного к клиенту:

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.get("/negotiate", async (req, res) => {
  let id = req.query.id;
  if (!id) {
    res.status(400).send("missing user id");
    return;
  }
  let token = await serviceClient.getClientAccessToken({ userId: id });
  res.json({
    url: token.url,
  });
});

app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

В приведенном выше коде onConnected просто выводит сообщение в консоль при подключении клиента. Мы используем метод req.context.userId, чтобы увидеть удостоверение подключенного клиента. И handleUserEvent вызывается при отправке клиентом сообщения. Он используется WebPubSubServiceClient.sendToAll() для трансляции сообщения в объекте JSON всем клиентам. В handleUserEvent также есть объект res, который позволяет отправить сообщение обратно отправителю события. Здесь мы просто вызываем возврат веб-перехватчика 200 (обратите внимание, res.success() что этот вызов необходим, даже если вы не хотите возвращать что-либо обратно клиенту, в противном случае веб-перехватчик никогда не возвращается и подключение клиента закрывается).

Java

Теперь необходимо реализовать обработчик событий собственным в Java. Эти действия выполняются непосредственно после спецификации протокола и показаны в следующем списке:

1. Добавьте обработчик HTTP-данных для пути обработчика событий, допустим /eventhandler.

2. Сначала нужно будет обработать запросы OPTIONS защиты от нарушения: мы проверяем, содержит ли запрос заголовок WebHook-Request-Origin, и возвращаем заголовок WebHook-Allowed-Origin. Для простоты в демонстрационных целях мы возвращаем *, чтобы разрешить все источники.

   
   // validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   app.options("/eventhandler", ctx -> {
       ctx.header("WebHook-Allowed-Origin", "*");
   });
   

3. Затем мы хотим проверить, являются ли входящие запросы ожидаемыми событиями. Предположим, что теперь нас интересует системное событие connected, которое должно содержать заголовок ce-type как azure.webpubsub.sys.connected. Мы добавим логику после защиты от злоупотреблений, чтобы транслировать подключенное событие ко всем клиентам, чтобы они могли видеть, кто присоединился к комнате чата.

   // validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   app.options("/eventhandler", ctx -> {
       ctx.header("WebHook-Allowed-Origin", "*");
   });
   
   // handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   app.post("/eventhandler", ctx -> {
       String event = ctx.header("ce-type");
       if ("azure.webpubsub.sys.connected".equals(event)) {
           String id = ctx.header("ce-userId");
           System.out.println(id + " connected.");
       }
       ctx.status(200);
   });
   
   

   В приведенном выше коде мы просто выводим сообщение в консоли при подключении клиента. Мы используем метод ctx.header("ce-userId"), чтобы увидеть удостоверение подключенного клиента.

4. message Событие ce-type всегда azure.webpubsub.user.message. Сведения см . в сообщении о событии. Мы обновляем логику для обработки сообщений, которые при передаче сообщения в формате JSON передаются всем подключенным клиентам.

   // handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   app.post("/eventhandler", ctx -> {
       String event = ctx.header("ce-type");
       if ("azure.webpubsub.sys.connected".equals(event)) {
           String id = ctx.header("ce-userId");
           System.out.println(id + " connected.");
       } else if ("azure.webpubsub.user.message".equals(event)) {
           String id = ctx.header("ce-userId");
           String message = ctx.body();
           Gson gson = new Gson();
           JsonObject jsonObject = new JsonObject();
           jsonObject.addProperty("from", id);
           jsonObject.addProperty("message", message);
           String messageToSend = gson.toJson(jsonObject);
           service.sendToAll(messageToSend, WebPubSubContentType.APPLICATION_JSON);
       }
       ctx.status(200);
   });
   

Python

Теперь необходимо реализовать обработчик событий собственным в Python. Эти шаги выполняются прямо после спецификации протокола и показаны в следующем списке:

1. Добавьте обработчик HTTP-данных для пути обработчика событий, допустим /eventhandler.

2. Сначала нужно будет обработать запросы OPTIONS защиты от нарушения: мы проверяем, содержит ли запрос заголовок WebHook-Request-Origin, и возвращаем заголовок WebHook-Allowed-Origin. Для простоты в демонстрационных целях мы возвращаем *, чтобы разрешить все источники.

   # validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   @app.route('/eventhandler', methods=['OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
   

3. Затем мы хотим проверить, являются ли входящие запросы ожидаемыми событиями. Предположим, что теперь нас интересует системное событие connected, которое должно содержать заголовок ce-type как azure.webpubsub.sys.connected. Мы добавляем логику после защиты от нарушения:

   # validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   # handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   @app.route('/eventhandler', methods=['POST', 'OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
       elif request.method == 'POST':
           user_id = request.headers.get('ce-userid')
           if request.headers.get('ce-type') == 'azure.webpubsub.sys.connected':
               return user_id + ' connected', 200
           else:
               return 'Not found', 404
   

   В приведенном выше коде мы просто выводим сообщение в консоли при подключении клиента. Мы используем метод request.headers.get('ce-userid'), чтобы увидеть удостоверение подключенного клиента.

4. message Событие ce-type всегда azure.webpubsub.user.message. Сведения см . в сообщении о событии. Мы обновляем логику для обработки сообщений, которые при передаче сообщения передаются всем подключенным клиентам.

   @app.route('/eventhandler', methods=['POST', 'OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
       elif request.method == 'POST':
           user_id = request.headers.get('ce-userid')
           type = request.headers.get('ce-type')
           if type == 'azure.webpubsub.sys.connected':
               print(f"{user_id} connected")
               return '', 204
           elif type == 'azure.webpubsub.user.message':
               # default uses JSON
               service.send_to_all(message={
                   'from': user_id,
                   'message': request.data.decode('UTF-8')
               })
               # returned message is also received by the client
               return {
                   'from': "system",
                   'message': "message handled by server"
               }, 200
           else:
               return 'Bad Request', 400
   

Обновление веб-страницы

Теперь давайте обновим index.html логику для подключения, отправки сообщения и отображения полученных сообщений на странице.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

В приведенном выше коде мы подключаем собственный API WebSocket в браузере и используем WebSocket.send() для отправки сообщений и WebSocket.onmessage прослушивания полученных сообщений.

Вы также можете использовать клиентские пакеты SDK для подключения к службе, что позволяет выполнять автоматическое повторное подключение, обработку ошибок и многое другое.

Теперь для работы чата осталось один шаг. Давайте настроим события, о которых мы заботимся, и где отправлять события в службу Web PubSub.

Настройка обработчика событий

Мы задали обработчик событий в службе Web PubSub, чтобы сообщить службе, куда отправлять события.

Когда веб-сервер выполняется локально, как служба Web PubSub вызывает localhost, если у нее нет конечной точки доступа к Интернету? Обычно существует два способа. Одним из них является предоставление локального узла общедоступным пользователям с помощью какого-то общего средства туннелирования, а другой — использовать awps-туннель для туннелирования трафика из службы Web PubSub через средство на локальный сервер.

В этом разделе мы используем Azure CLI для задания обработчиков событий и использования awps-tunnel для маршрутизации трафика в localhost.

Настройка параметров концентратора

Мы задали шаблон URL-адреса для использования tunnel схемы, чтобы Web PubSub направляет сообщения через awps-tunnelтуннельное подключение. Обработчики событий можно задать на портале или интерфейсе командной строки, как описано в этой статье, здесь мы зададим его через CLI. Так как мы прослушиваем события в пути /eventhandler в качестве предыдущих наборов шагов, мы зададим шаблон tunnel:///eventhandlerURL-адреса.

Используйте команду создания azure CLI az webpubsub hub, чтобы создать параметры обработчика событий для концентратораSample_ChatApp.

Внимание

Замените <your-unique-resource-name> на имя ресурса Web PubSub, созданного на предыдущих шагах.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

Локальное выполнение awps-туннеля

Скачивание и установка awps-tunnel

Средство работает на Node.js версии 16 или более поздней.

npm install -g @azure/web-pubsub-tunnel-tool

Использование службы строка подключения и запуск

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Запуск веб-сервера

Теперь все задано. Давайте запустите веб-сервер и сыграем с приложением чата в действии.

C#

Теперь запустите сервер с помощью dotnet run --urls http://localhost:8080.

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

JavaScript

Теперь запустите сервер с помощью node server.

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

Java

Теперь запустите сервер с помощью следующей команды:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

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

Python

Теперь запустите сервер с помощью python server.py.

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

Открыть http://localhost:8080/index.html. Вы можете ввести имя пользователя и начать чат.

Отложенная проверка подлинности с connect обработчиком событий

В предыдущих разделах показано, как использовать конечную точку согласования для возврата URL-адреса службы Web PubSub и маркера доступа JWT для клиентов для подключения к службе Web PubSub. В некоторых случаях, например, пограничные устройства с ограниченными ресурсами, клиенты могут предпочесть прямое подключение к ресурсам Web PubSub. В таких случаях обработчик событий можно настроить connect для отложенной проверки подлинности клиентов, назначить идентификатор пользователя клиентам, указать группы, которые клиенты присоединяются после подключения, настроить разрешения клиентов и subprotocol WebSocket в качестве ответа WebSocket клиенту и т. д. Дополнительные сведения см. в спецификации обработчика событий.

Теперь давайте используем connect обработчик событий для достижения аналогичного того, что делает раздел переговоров .

Обновление параметров центра

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

Используйте команду центра обновления Azure CLI az webpubsub hub, чтобы создать параметры обработчика событий для концентратораSample_ChatApp.

Внимание

Замените <your-unique-resource-name> на имя ресурса Web PubSub, созданного на предыдущих шагах.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Обновление логики вышестоящий для обработки события подключения

Теперь давайте обновим логику вышестоящий для обработки события подключения. Теперь можно удалить конечную точку переговоров.

Аналогично тому, что мы делаем в согласовании конечной точки в качестве демонстрационной цели, мы также считываем идентификатор из параметров запроса. При подключении исходный запрос клиента сохраняется в тексте повторного запроса события подключения.

C#

В классе Sample_ChatAppпереопределите OnConnectAsync() для обработки connect события:

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

JavaScript

Обновите server.js для обработки события подключения клиента:

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  handleConnect: async (req, res) => {
    if (req.context.query.id){
      res.success({ userId: req.context.query.id });
    } else {
      res.fail(401, "missing user id");
    }
  },
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

Java

Теперь добавим логику для обработки события azure.webpubsub.sys.connectподключения:

// validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#connect
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connect".equals(event)) {
        String body = ctx.body();
        System.out.println("Reading from request body...");
        Gson gson = new Gson();
        JsonObject requestBody = gson.fromJson(body, JsonObject.class); // Parse JSON request body
        JsonObject query = requestBody.getAsJsonObject("query");
        if (query != null) {
            System.out.println("Reading from request body query:" + query.toString());
            JsonElement idElement = query.get("id");
            if (idElement != null) {
                JsonArray idInQuery = query.get("id").getAsJsonArray();
                if (idInQuery != null && idInQuery.size() > 0) {
                    String id = idInQuery.get(0).getAsString();
                    ctx.contentType("application/json");
                    Gson response = new Gson();
                    JsonObject jsonObject = new JsonObject();
                    jsonObject.addProperty("userId", id);
                    ctx.result(response.toJson(jsonObject));
                    return;
                }
            }
        } else {
            System.out.println("No query found from request body.");
        }
        ctx.status(401).result("missing user id");
    } else if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
        ctx.status(200);
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        service.sendToAll(String.format("{\"from\":\"%s\",\"message\":\"%s\"}", id, message), WebPubSubContentType.APPLICATION_JSON);
        ctx.status(200);
    }
});

Python

Теперь давайте обработаем системное connect событие, которое должно содержать заголовок ce-type как azure.webpubsub.sys.connect. Мы добавляем логику после защиты от нарушения:

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS' or request.method == 'GET':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        print("Received event of type:", type)
        # Sample connect logic if connect event handler is configured
        if type == 'azure.webpubsub.sys.connect':
            body = request.data.decode('utf-8')
            print("Reading from connect request body...")
            query = json.loads(body)['query']
            print("Reading from request body query:", query)
            id_element = query.get('id')
            user_id = id_element[0] if id_element else None
            if user_id:
                return {'userId': user_id}, 200
            return 'missing user id', 401
        elif type == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        elif type == 'azure.webpubsub.user.message':
            service.send_to_all(content_type="application/json", message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            return Response(status=204, content_type='text/plain')
        else:
            return 'Bad Request', 400

Обновление index.html для прямого подключения

Теперь обновим веб-страницу, чтобы напрямую подключиться к службе Web PubSub. Одно из упоминание заключается в том, что теперь для демонстрации конечной точки службы Web PubSub жестко закодирован в клиентский код, обновите имя <the host name of your service> узла службы в приведенном ниже html значении из собственной службы. Возможно, вам по-прежнему полезно получить значение конечной точки службы Web PubSub с сервера, что обеспечивает большую гибкость и управляемость, к которой подключается клиент.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Повторное запуск сервера

Теперь повторно запустите сервер и перейдите на веб-страницу после инструкций, описанных ранее. Если вы остановили awps-tunnel, также повторно запустите средство туннелирования.

Следующие шаги

В этом руководстве вы узнаете, как работает система событий в службе Azure Web PubSub.

Чтобы узнать больше об использовании службы, ознакомьтесь с другими учебниками.

Другие примеры Azure Web PubSub