Início Rápido: publicar mensagens usando o SDK do serviço Azure Web PubSub

O Azure Web PubSub ajuda você a gerenciar clientes WebSocket. Este início rápido mostra como publicar mensagens para clientes WebSocket usando o SDK do serviço Azure Web PubSub.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma, crie uma conta gratuita.
• um shell de comando Bash e PowerShell. As amostras de Python, JavaScript e Java exigem um shell de comando Bash.
• Um editor de arquivos como VSCode.
• CLI do Azure: instalar a CLI do Azure

Se estiver criando o projeto em um computador local, você precisará instalar as dependências da linguagem que estiver usando:

C#

Instale o SDK do .NET Core e o aspnetcore e o dotnet runtime.

.NET Core

JavaScript

Node.js

Python

Python

Java

• JDK (Java Development Kit)
• Apache Maven

1. Instalação

Para entrar no Azure usando a CLIl, execute o comando a seguir e siga os prompts para concluir o processo de autenticação. Se você estiver usando Cloud Shell, não será necessário entrar.

az login

Verifique se você está executando a versão mais recente da CLI com o comando de atualização.

az upgrade

Em seguida, instale ou atualize a extensão do Azure Web PubSub para a CLI se ela não foi instalada com az upgrade.

az extension add --name webpubsub --upgrade

1. Criar um grupo de recursos

Defina as variáveis de ambiente a seguir. Substitua o <espaço reservado> por um nome do Web PubSub exclusivo.

Bash

RESOURCE_GROUP="webpubsub-resource-group"
LOCATION="EastUS"
WEB_PUBSUB_NAME="<your-unique-name>"

PowerShell do Azure

$ResourceGroupName = 'webpubsub-resource-group'
$Location = 'EastUS'
$WebPubSubName = '<YourUniqueName>'

Crie um grupo de recursos para o projeto do Web PubSub.

Bash

az group create \
  --name $RESOURCE_GROUP \
  --location $LOCATION

PowerShell do Azure

az group create --location $Location --name $ResourceGroupName

2. Implantar uma instância de serviço do Web PubSub

Use o comando az webpubsub create para criar e implantar uma instância de serviço do Web PubSub.

Bash

az webpubsub create \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --sku Free_F1

PowerShell do Azure

az webpubsub create `
  --name $WebPubSubName `
  --location $Location `
  --resource-group $ResourceGroupName `
  --sku Free_F1

Salve a cadeia de conexão do serviço. A cadeia de conexão é usada pelo SDK do serviço para publicar mensagens.

Importante

Em um ambiente de produção, você deve armazenar com segurança cadeias de conexão usando o Azure Key Vault.

Bash

az webpubsub key show --name $WEB_PUBSUB_NAME --resource-group $RESOURCE_GROUP --query primaryConnectionString

PowerShell do Azure

az webpubsub key show --name $WebPubSubName --resource-group $ResourceGroupName --query primaryConnectionString

3. Conectar um cliente à instância de serviço

Crie um cliente do Web PubSub. O cliente mantém uma conexão com o serviço até que ele seja encerrado.

Use o comando az webpubsub client para iniciar uma conexão de cliente WebSocket ao serviço. Os clientes sempre se conectam a um hub. Portanto, forneça um nome de hub para o cliente se conectar.

Bash

az webpubsub client start \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --hub-name "myHub1" \
  --user-id "user1"

PowerShell do Azure

az webpubsub client start `
  --name $WebPubSubName `
  --resource-group $ResourceGroupName `
  --hub-name 'myHub1' `
  --user-id 'user1' 

A conexão ao serviço Web PubSub é estabelecida quando você vir uma mensagem JSON, indicando que o cliente agora está conectado com êxito e foi atribuído com um connectionId exclusivo:

{"type":"system","event":"connected","userId":"user1","connectionId":"<your_unique_connection_id>"}

4. Publicar mensagens usando o SDK do serviço

Você usará o SDK do Azure Web PubSub para publicar uma mensagem para todos os clientes conectados ao hub. É possível escolher entre C#, JavaScript, Python e Java. As dependências de cada linguagem são instaladas nas etapas para essa linguagem. Python, JavaScript e Java exigem um shell bash para executar os comandos neste início rápido.

Configurar o projeto para publicar mensagens

1. Abra um novo shell de comando para este projeto.

2. Salve a cadeia de conexão do shell do cliente. Substitua o espaço reservado <your_connection_string> pela cadeia de conexão exibida em uma etapa anterior.

   Bash

   connection_string="<your_connection_string>"
   

   PowerShell do Azure

   $connection_string = "<your_connection_string>"
   

3. Agora, selecione a linguagem do projeto.

C#

1. Adicione um novo projeto nomeado como publisher e adicione o pacote do SDK Azure.Messaging.WebPubSub.

   mkdir publisher
   cd publisher
   dotnet new console
   dotnet add package Azure.Messaging.WebPubSub
   

2. Atualize o arquivo Program.cs para usar a classe WebPubSubServiceClient e enviar mensagens aos clientes. Substitua o código no arquivo Program.cs pelo código a seguir.

   using System;
   using System.Threading.Tasks;
   using Azure.Messaging.WebPubSub;
   
   namespace publisher
   {
       class Program
       {
           static async Task Main(string[] args)
           {
               if (args.Length != 3) {
                   Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                   return;
               }
               var connectionString = args[0];
               var hub = args[1];
               var message = args[2];
   
               var service = new WebPubSubServiceClient(connectionString, hub);
   
               // Send messages to all the connected clients
               // You can also try SendToConnectionAsync to send messages to the specific connection
               await service.SendToAllAsync(message);
           }
       }
   }
   

   A chamada service.SendToAllAsync() simplesmente envia uma mensagem a todos os clientes conectados no hub.

3. Execute o comando a seguir para publicar uma mensagem no serviço.

   dotnet run $connection_string "myHub1" "Hello World"
   

4. O shell de comando anterior que contém o cliente Web PubSub mostra a mensagem recebida.

   {"type":"message","from":"server","dataType":"text","data":"Hello World"}
   

JavaScript

1. Crie uma nova pasta nomeada como publisher para este projeto e instale as dependências necessárias:

   mkdir publisher
   cd publisher
   npm init -y
   npm install --save @azure/web-pubsub
   

2. Use o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Crie um arquivo publish.js contendo o código:

   const { WebPubSubServiceClient } = require('@azure/web-pubsub');
   
   if (process.argv.length !== 3) {
     console.log('Usage: node publish <message>');
     return 1;
   }
   const hub = "myHub1";
   let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
   // by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
   service.sendToAll(process.argv[2], { contentType: "text/plain" });
   

   A chamada sendToAll() simplesmente envia uma mensagem a todos os clientes conectados em um hub.

3. Execute o comando a seguir para publicar uma mensagem no serviço:

   export WebPubSubConnectionString=$connection_string
   node publish "Hello World"
   

4. O shell de comando anterior que contém o cliente Web PubSub mostra a mensagem recebida.

   {"type":"message","from":"server","dataType":"text","data":"Hello World"}
   

Python

1. Crie uma nova pasta nomeada como publisher para este projeto e instale as dependências necessárias:

   mkdir publisher
   cd publisher
   # Create venv
   python -m venv env
   # Active venv
   source ./env/bin/activate
   pip install azure-messaging-webpubsubservice
   

2. Use o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Crie um arquivo publish.py com o código abaixo:

   import sys
   from azure.messaging.webpubsubservice import WebPubSubServiceClient
   
   if __name__ == '__main__':
   
       if len(sys.argv) != 4:
           print('Usage: python publish.py <connection-string> <hub-name> <message>')
           exit(1)
   
       connection_string = sys.argv[1]
       hub_name = sys.argv[2]
       message = sys.argv[3]
   
       service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
       res = service.send_to_all(message, content_type='text/plain')
       print(res)
   

   O método service.send_to_all() envia uma mensagem a todos os clientes conectados em um hub.

3. Execute o comando a seguir para publicar uma mensagem no serviço:

   python publish.py $connection_string "myHub1" "Hello World"
   

4. O shell de comando anterior que contém o cliente Web PubSub mostra a mensagem recebida.

   {"type":"message","from":"server","dataType":"text","data":"Hello World"}
   

Java

1. Use o Maven para criar um novo aplicativo de console nomeado como webpubsub-quickstart-publisher e ir para o diretório webpubsub-quickstart-publisher:

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

2. Adicione o SDK do Azure Web PubSub ao nó dependencies do pom.xml:

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

3. Vá para o diretório /src/main/java/com/webpubsub/quickstart.

4. Substitua o conteúdo no arquivo App.java pelo código a seguir:

   package com.webpubsub.quickstart;
   
   import com.azure.messaging.webpubsub.*;
   import com.azure.messaging.webpubsub.models.*;
   
   /**
   * Publish messages using Azure Web PubSub service SDK
   *
   */
   public class App 
   {
       public static void main( String[] args )
       {
           if (args.length != 3) {
               System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
               return;
           }
   
           WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
               .connectionString(args[0])
               .hub(args[1])
               .buildClient();
           service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
       }
   }
   
   

   Este código usa o SDK do Azure Web PubSub para publicar uma mensagem no serviço. A chamada service.sendToAll() envia uma mensagem a todos os clientes conectados em um hub.

5. Retorne ao o diretório webpubsub-quickstart-publisher que contém o arquivo pom.xml e compile o projeto usando o comando mvn a seguir.

   mvn compile
   

6. Crie o pacote.

   mvn package
   

7. Execute o comando mvn a seguir para executar o aplicativo para publicar uma mensagem no serviço:

   mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args=" '$connection_string' 'myHub1' 'Hello World'"
   

8. O shell de comando anterior que contém o cliente Web PubSub mostra a mensagem recebida.

   {"type":"message","from":"server","dataType":"text","data":"Hello World"}
   

Limpeza

Você pode excluir os recursos criados neste início rápido excluindo o grupo de recursos que os contém.

Bash

az group delete --name $RESOURCE_GROUP --yes

PowerShell do Azure

d

az group delete --name $ResourceGroup --yes

Próximas etapas

Este guia de início rápido fornece uma ideia básica de como se conectar ao serviço Web PubSub e como publicar mensagens nos clientes conectados.

Em aplicativos do mundo real, você pode usar SDKs em várias linguagens para criar seu próprio aplicativo. Também fornecemos extensões de Função para você criar aplicativos sem servidor com facilidade.

Use estes recursos para começar a criar seu aplicativo:

Tutorial: Publicar e assinar mensagens no Azure Web PubSub

Tutorial: criar uma sala de chat simples com o Azure Web PubSub

Tutorial: Usar um subprotocolo com suporte do serviço para streaming de cliente

Tutorial: Criar um chat sem servidor com o Azure Functions e o Web PubSub

Tutorial: Configurar um ouvinte de eventos

Experimentar demonstrações ao vivo

Explorar mais exemplos do Azure Web PubSub