O modelo familiar de solicitação/resposta HTTP foi projetado para ser fácil de trabalhar e escalável. No entanto, hoje em dia os usuários finais exigem muito mais da web do que ela foi originalmente projetada. O protocolo HTTP requer que os usuários iniciem a solicitação para receber uma resposta. Mas os desenvolvedores precisam de uma maneira de enviar dados do servidor para os clientes sem que eles peçam; Em outras palavras, eles precisam "empurrar " dados para os clientes, como empurrar o preço de licitação mais recente de um produto em um site de leilões ou preços de ações em rápida evolução em uma aplicação financeira.
Este guia de início rápido demonstra como
Inscrever-se em mensagens de um servidor de aplicativos
Enviar dados por push de um servidor de aplicativos para todos os clientes conectados
Importante
As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração.
Uma cadeia de conexão inclui as informações de autorização necessárias para seu aplicativo acessar o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha de root para o seu serviço. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua conexão com WebPubSubServiceCliento .
Evite distribuir chaves de acesso para outros usuários, codificá-las ou salvá-las em qualquer lugar em texto simples acessível a outras pessoas. Rode as chaves se acreditar que podem ter sido comprometidas.
Pré-requisitos
Um recurso Web PubSub. Se você ainda não criou um, você pode seguir as orientações: Criar um recurso Web PubSub
Um editor de código, como o Visual Studio Code
Instalar as dependências para o idioma que você planeja usar
Para assinar mensagens enviadas por push do seu servidor de aplicativos, um cliente, seja um navegador, um aplicativo móvel ou um dispositivo IoT, precisa se conectar ao seu recurso Web PubSub primeiro e escuta o evento de mensagem apropriado.
Criar um diretório de projeto chamado subscriber e instalar as dependências necessárias
mkdir subscriber
cd subscriber
npm init -y
# The client SDK is available as a module on NPM
npm install @azure/web-pubsub-client
Conecte-se ao seu recurso Web PubSub e registre um ouvinte para o server-message evento
Um cliente usa uma URL de Acesso para Cliente para se conectar e autenticar com seu recurso.
Este URL segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Um cliente pode ter algumas maneiras de obter a URL de Acesso para Cliente. Para este início rápido, você pode copiar e colar um do portal do Azure mostrado no diagrama a seguir. É uma prática recomendada não codificar a URL de Acesso para Cliente em seu código. No mundo da produção, geralmente configuramos um servidor de aplicativos para retornar essa URL sob demanda. Gerar URL de Acesso para Cliente descreve a prática em detalhes.
Como mostrado no diagrama acima, o cliente ingressa no hub chamado myHub1.
Na pasta do subscriber projeto, crie um arquivo nomeado subscribe.js com o seguinte código
const { WebPubSubClient } = require("@azure/web-pubsub-client");
// Instantiates the client object
// <client-access-url> is copied from Azure portal mentioned above
const client = new WebPubSubClient("<client-access-url>")
// Registers a handler for the "server-message" event
client.on("server-message", (e) => {
console.log(`Received message ${e.message.data}`)
});
// Before a client can receive a message,
// you must invoke start() on the client object.
client.start();
Execute o programa
node subscribe.js
Agora, esse cliente estabelece uma conexão com seu recurso Web PubSub e está pronto para receber mensagens enviadas por push do seu servidor de aplicativos.
Criar um diretório de projeto chamado subscriber e instalar as dependências necessárias
mkdir subscriber
cd subscriber
# Create a .net console app
dotnet new console
# Add the client SDK
dotnet add package Azure.Messaging.WebPubSub.Client --prerelease
Conecte-se ao seu recurso Web PubSub e registre um ouvinte para o ServerMessageReceived evento
Um cliente usa uma URL de Acesso para Cliente para se conectar e autenticar com seu recurso.
Este URL segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Um cliente pode ter algumas maneiras de obter a URL de Acesso para Cliente. Para este início rápido, você pode copiar e colar um do portal do Azure mostrado no diagrama a seguir. É uma prática recomendada não codificar a URL de Acesso para Cliente em seu código. No mundo da produção, geralmente configuramos um servidor de aplicativos para retornar essa URL sob demanda. Gerar URL de Acesso para Cliente descreve a prática em detalhes.
Como mostrado no diagrama acima, o cliente ingressa no hub chamado myHub1.
Substitua o código no Program.cs com o seguinte código
using Azure.Messaging.WebPubSub.Clients;
// Instantiates the client object
// <client-access-uri> is copied from Azure portal mentioned above
var client = new WebPubSubClient(new Uri("<client-access-uri>"));
client.ServerMessageReceived += eventArgs =>
{
Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
return Task.CompletedTask;
};
client.Connected += eventArgs =>
{
Console.WriteLine("Connected");
return Task.CompletedTask;
};
await client.StartAsync();
// This keeps the subscriber active until the user closes the stream by pressing Ctrl+C
var streaming = Console.ReadLine();
while (streaming != null)
{
if (!string.IsNullOrEmpty(streaming))
{
await client.SendToGroupAsync("stream", BinaryData.FromString(streaming + Environment.NewLine), WebPubSubDataType.Text);
}
streaming = Console.ReadLine();
}
await client.StopAsync();
Execute o seguinte comando
dotnet run
Agora, esse cliente estabelece uma conexão com seu recurso Web PubSub e está pronto para receber mensagens enviadas por push do seu servidor de aplicativos.
Crie um diretório de projeto chamado subscriber e instale as dependências necessárias:
Use a API WebSocket para se conectar ao recurso Web PubSub. Crie um subscribe.py arquivo com o seguinte código
import asyncio
import sys
import websockets
from azure.messaging.webpubsubservice import WebPubSubServiceClient
async def connect(url):
async with websockets.connect(url) as ws:
print('connected')
while True:
print('Received message: ' + await ws.recv())
if __name__ == '__main__':
if len(sys.argv) != 3:
print('Usage: python subscribe.py <connection-string> <hub-name>')
exit(1)
connection_string = sys.argv[1]
hub_name = sys.argv[2]
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
token = service.get_client_access_token()
try:
asyncio.get_event_loop().run_until_complete(connect(token['url']))
except KeyboardInterrupt:
pass
O código cria uma conexão WebSocket que está conectada a um hub no Web PubSub. Um hub é uma unidade lógica no Web PubSub onde você pode publicar mensagens para um grupo de clientes. Os conceitos-chave contêm a explicação detalhada sobre os termos usados no Web PubSub.
O serviço Web PubSub usa autenticação JSON Web Token (JWT). O código de exemplo usa WebPubSubServiceClient.GetClientAccessUri() no Web PubSub SDK para gerar uma URL para o serviço que contém a URL completa com um token de acesso válido.
Depois que a conexão for estabelecida, seu cliente receberá mensagens através da conexão WebSocket. Use await ws.recv() para ouvir as mensagens recebidas.
Execute o seguinte comando
python subscribe.py $connection_string "myHub1"
Criar um diretório de projeto chamado pubsub
mkdir pubsub
cd pubsub
Use o Maven para criar um novo aplicativo de console chamado webpubsub-quickstart-subscriber;
No Web PubSub, você pode se conectar ao serviço e assinar mensagens por meio de conexões WebSocket. WebSocket é um canal de comunicação full-duplex que permite ao serviço enviar mensagens para o seu cliente em tempo real. Você pode usar qualquer API ou biblioteca que ofereça suporte a WebSocket. Para este exemplo, usamos o pacote Java-WebSocket.
Vá para o diretório /src/main/java/com/webpubsub/quickstart .
Editar substitua o conteúdo do arquivo App.java com o seguinte código:
package com.webpubsub.quickstart;
import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App
{
public static void main( String[] args ) throws IOException, URISyntaxException
{
if (args.length != 2) {
System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
return;
}
WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
.connectionString(args[0])
.hub(args[1])
.buildClient();
WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());
WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
@Override
public void onMessage(String message) {
System.out.println(String.format("Message received: %s", message));
}
@Override
public void onClose(int arg0, String arg1, boolean arg2) {
// TODO Auto-generated method stub
}
@Override
public void onError(Exception arg0) {
// TODO Auto-generated method stub
}
@Override
public void onOpen(ServerHandshake arg0) {
// TODO Auto-generated method stub
}
};
webSocketClient.connect();
System.in.read();
}
}
Esse código cria uma conexão WebSocket conectada a um hub no Azure Web PubSub. Um hub é uma unidade lógica no Azure Web PubSub onde você pode publicar mensagens para um grupo de clientes. Os principais conceitos contêm a explicação detalhada sobre os termos usados no Azure Web PubSub.
O serviço Web PubSub usa autenticação JSON Web Token (JWT). O código de exemplo usa WebPubSubServiceClient.GetClientAccessUri() no Web PubSub SDK para gerar uma URL para o serviço que contém a URL completa com um token de acesso válido.
Depois que a conexão for estabelecida, seu cliente receberá mensagens através da conexão WebSocket. Use onMessage(String message) para ouvir as mensagens recebidas.
Enviar mensagens por push do seu servidor de aplicativos
Agora que você tem um cliente conectado ao seu recurso Web PubSub, você pode enviar mensagens por push de um servidor de aplicativos a qualquer momento usando o SDK do servidor fornecido pelo Web PubSub.
Criar um novo diretório de projeto chamado publisher e instalar as dependências necessárias
mkdir publisher
cd publisher
npm init
# This command installs the server SDK from NPM,
# which is different from the client SDK you used in subscribe.js
npm install --save @azure/web-pubsub
Crie um publish.js arquivo com o seguinte código
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
// This is the hub name we used on Azure portal when generating the Client Access URL.
// It ensures this server can push messages to clients in the hub named "myHub1".
const hub = "myHub1";
let server = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
// By default, the content type is `application/json`.
// Specify contentType as `text/plain` for this demo.
server.sendToAll(process.argv[2], { contentType: "text/plain" });
A server.sendToAll() chamada envia uma mensagem para todos os clientes conectados em um hub.
Obter a cadeia de ligação
Importante
Uma cadeia de conexão inclui informações de autorização necessárias para que seu aplicativo acesse o serviço Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha de root para o seu serviço.
Para este guia de início rápido, vamos obtê-lo no portal do Azure, conforme mostrado abaixo.
Execute o programa do servidor
Execute os seguintes comandos em um novo shell de comando.
As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua conexão com WebPubSubServiceCliento .
# Set the environment variable for your connection string.
export WebPubSubConnectionString="<Put your connection string here>"
node publish.js "Hello World"
Observe as mensagens recebidas no lado do cliente
Tente executar o mesmo programa "subscribe" em vários shells de comando para estimular mais do que os clientes. Assim que o programa "publicar" é executado, você deve ver as mensagens sendo entregues em tempo real para todos esses clientes.
Crie um diretório de projeto chamado publisher e instale as dependências necessárias:
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
Substitua o Program.cs arquivo 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];
// Either generate the token or fetch it from server or fetch a temp one from the portal
var serviceClient = new WebPubSubServiceClient(connectionString, hub);
await serviceClient.SendToAllAsync(message);
}
}
}
A SendToAllAsync() chamada envia uma mensagem para todos os clientes conectados no hub.
Execute o programa do servidor para enviar mensagens por push para todos os clientes conectados
$connection_string="<connection-string>"
dotnet run $connection_string "myHub1" "Hello World"
Observe as mensagens recebidas no lado do cliente
# On the command shell used for running the "subscribe" program, you should see the received the messaged logged there.
# Try running the same "subscribe" program in multiple command shells, which simulates more than clients.
# Try running the "publish" program several times and you see messages being delivered in real-time to all these clients.
Message received: Hello World
Primeiro, crie um diretório de projeto chamado publisher 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
Use o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Crie um publish.py arquivo 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 send_to_all() enviar a mensagem para todos os clientes conectados em um hub.
Verifique o shell de comando anterior para que o assinante recebeu a mensagem:
Received message: Hello World
Vá para o pubsub diretório. Use o Maven para criar um aplicativo webpubsub-quickstart-publisher de console do publisher e vá para o diretório webpubsub-quickstart-publisher :
Use o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Vá para o diretório /src/main/java/com/webpubsub/quickstart , abra o arquivo App.java no editor e substitua o conteúdo pelo seguinte código:
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);
}
}
A sendToAll() chamada envia uma mensagem para todos os clientes conectados em um hub.
Vá para o diretório webpubsub-quickstart-publisher e execute o projeto usando o seguinte comando:
Você pode ver que o assinante anterior recebeu a mensagem:
Message received: Hello World
Resumo
Este guia de início rápido demonstra como é fácil enviar mensagens de um servidor de aplicativos para todos os clientes conectados em um hub. Além disso, Web PubSub permite que você envie mensagens para
Um subconjunto dos clientes em um hub
um grupo específico em um hub
um subconjunto de clientes em um grupo
Essas APIs permitem uma grande variedade de casos de uso, permitindo que os desenvolvedores se concentrem em uma lógica de negócios exclusiva, ao mesmo tempo em que têm a certeza de que o Web PubSub oferece baixa latência (<100ms), alta disponibilidade e escala massiva (milhões + conexões simultâneas).
Próximos passos
Na próxima etapa, exploraremos como trabalhar com o sistema de eventos do Web PubSub, necessário para construir aplicações web completas.
