O modelo de pedido/resposta HTTP familiar foi concebido para ser fácil de trabalhar e dimensionável. No entanto, hoje em dia os utilizadores finais exigem muito mais da Web do que foram originalmente concebidos. O protocolo HTTP requer que os utilizadores iniciem o pedido para receberem uma resposta. No entanto, os programadores precisam de uma forma de enviar dados do servidor para os clientes sem que estes os peçam; por outras palavras, precisam de "emitir" dados para os clientes, como emitir o preço de licitação mais recente de um produto num site de leilões ou mover rapidamente os preços das ações numa aplicação financeira.
Este guia de início rápido demonstra como
subscrever mensagens de um servidor de aplicações
enviar dados de um servidor de aplicações para todos os clientes ligados
Pré-requisitos
Um recurso Web PubSub. Se ainda não criou um, pode seguir a documentação de orientação: Criar um recurso Web PubSub
Um editor de código, como o Visual Studio Code
Instalar as dependências do idioma que planeia utilizar
Para subscrever mensagens enviadas a partir do servidor de aplicações, um cliente, seja um browser, uma aplicação móvel ou um dispositivo IoT, tem de ligar primeiro ao recurso Web PubSub e escutar o evento de mensagem adequado.
Criar um diretório de projeto com o nome 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
Ligar ao recurso Web PubSub e registar um serviço de escuta para o server-message evento
Um cliente utiliza um URL de Acesso de Cliente para se ligar e autenticar com o 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 formas de obter o URL de Acesso do Cliente. Para este guia de introdução, pode copiar e colar um dos portal do Azure apresentados no diagrama seguinte. É melhor prática não codificar o URL de Acesso do Cliente no seu código. No mundo da produção, normalmente, configuramos um servidor de aplicações para devolver este URL a pedido.
Gerar URL de Acesso de Cliente descreve a prática em detalhe.
Conforme mostrado no diagrama acima, o cliente associa-se ao hub com o nome myHub1.
Na pasta do subscriber projeto, crie um ficheiro com o nome 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, este cliente estabelece uma ligação com o recurso Web PubSub e está pronto para receber mensagens enviadas a partir do servidor da aplicação.
Criar um diretório de projeto com o nome 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
Ligar ao recurso Web PubSub e registar um serviço de escuta para o ServerMessageReceived evento
Um cliente utiliza um URL de Acesso de Cliente para se ligar e autenticar com o 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 formas de obter o URL de Acesso do Cliente. Para este guia de introdução, pode copiar e colar um dos portal do Azure apresentados no diagrama seguinte. É melhor prática não codificar o URL de Acesso do Cliente no seu código. No mundo da produção, normalmente, configuramos um servidor de aplicações para devolver este URL a pedido.
Gerar URL de Acesso de Cliente descreve a prática em detalhe.
Conforme mostrado no diagrama acima, o cliente associa-se ao hub com o nome myHub1.
Substitua o código no Program.cs pelo 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, este cliente estabelece uma ligação com o recurso Web PubSub e está pronto para receber mensagens enviadas a partir do servidor da aplicação.
Crie um diretório de projeto com o nome subscriber e instale as dependências necessárias:
Utilize a API WebSocket para ligar ao recurso Web PubSub. Criar um subscribe.py ficheiro 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 ligação WebSocket que está ligada a um hub no Web PubSub. Um hub é uma unidade lógica no Web PubSub onde pode publicar mensagens num grupo de clientes.
Os principais conceitos contêm a explicação detalhada sobre os termos utilizados no Web PubSub.
O serviço Web PubSub utiliza a autenticação JSON Web Token (JWT ). O código de exemplo utiliza WebPubSubServiceClient.GetClientAccessUri() no SDK Web PubSub para gerar um URL para o serviço que contém o URL completo com um token de acesso válido.
Após a ligação ser estabelecida, o cliente receberá mensagens através da ligação WebSocket. Utilize await ws.recv() para ouvir mensagens recebidas.
Execute o seguinte comando
python subscribe.py $connection_string "myHub1"
Criar um diretório de projeto com o nome pubsub
mkdir pubsub
cd pubsub
Utilize o Maven para criar uma nova aplicação de consola chamada webpubsub-quickstart-subscriber;
No Web PubSub, pode ligar ao serviço e subscrever mensagens através de ligações WebSocket. O WebSocket é um canal de comunicação completo e duplex que permite que o serviço envie mensagens para o seu cliente em tempo real. Pode utilizar qualquer API ou biblioteca que suporte WebSocket. Para este exemplo, utilizamos o pacote Java-WebSocket.
Aceda ao diretório /src/main/java/com/webpubsub/quickstart .
Editar substitua o conteúdo do ficheiro App.java pelo 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();
}
}
Este código cria uma ligação WebSocket que está ligada a um hub no Azure Web PubSub. Um hub é uma unidade lógica no Azure Web PubSub onde pode publicar mensagens num grupo de clientes.
Os principais conceitos contêm a explicação detalhada sobre os termos utilizados no Azure Web PubSub.
O serviço Web PubSub utiliza a autenticação JSON Web Token (JWT ). O código de exemplo utiliza WebPubSubServiceClient.GetClientAccessUri() no SDK Web PubSub para gerar um URL para o serviço que contém o URL completo com um token de acesso válido.
Após a ligação ser estabelecida, o cliente receberá mensagens através da ligação WebSocket. Utilize onMessage(String message) para ouvir mensagens recebidas.
Enviar mensagens push a partir do servidor de aplicações
Agora que tem um cliente ligado ao recurso Web PubSub, pode enviar mensagens push a partir de um servidor de aplicações em qualquer altura através do SDK do servidor fornecido pelo Web PubSub.
Criar um novo diretório de projeto com o nome 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
Criar um publish.js ficheiro 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 a todos os clientes ligados num hub.
Obter a cadeia de ligação
Importante
Uma cadeia de ligação inclui informações de autorização necessárias para que a sua aplicação aceda ao serviço Web PubSub. A chave de acesso dentro da cadeia de ligação é semelhante a uma palavra-passe de raiz para o seu serviço.
Para este guia de início rápido, vamos obtê-lo a partir de portal do Azure conforme mostrado abaixo.
Executar o programa de servidor
Execute os seguintes comandos numa nova shell de comandos.
# Set the environment variable for your connection string.
export WebPubSubConnectionString="<Put your connection string here>"
node publish.js "Hello World"
Observar as mensagens recebidas no lado do cliente
Experimente executar o mesmo programa "subscrever" em várias shells de comandos para estimular mais do que os clientes. Assim que o programa de "publicação" for executado, deverá ver mensagens a serem entregues em tempo real a todos estes clientes.
Crie um diretório de projeto com o nome 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 ficheiro pelo seguinte código
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 a todos os clientes ligados no hub.
Executar o programa de servidor para enviar mensagens push para todos os clientes ligados
$connection_string="<connection-string>"
dotnet run $connection_string "myHub1" "Hello World"
Observar 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 simluates 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 com o nome 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
Utilize o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Crie um publish.py ficheiro 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)
Envie send_to_all() a mensagem a todos os clientes ligados num hub.
Verifique a shell de comandos anterior para a qual o subscritor recebeu a mensagem:
Received message: Hello World
Aceda ao pubsub diretório. Utilize o Maven para criar uma aplicação webpubsub-quickstart-publisher de consola do publicador e aceda ao diretório webpubsub-quickstart-publisher :
Utilize o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Aceda ao diretório /src/main/java/com/webpubsub/quickstart , abra o ficheiro App.java no seu editor e substitua os conteúdos 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 a todos os clientes ligados num hub.
Aceda ao diretório webpubsub-quickstart-publisher e execute o projeto com o seguinte comando:
Pode ver que o subscritor anterior recebeu a mensagem:
Message received: Hello World
Resumo
Este início rápido demonstra como é fácil enviar mensagens de um servidor de aplicações para todos os clientes ligados num hub. Além disso, o Web PubSub permite-lhe enviar mensagens push para
um subconjunto dos clientes num hub
um grupo específico num hub
um subconjunto de clientes num grupo
Estas APIs permitem uma grande quantidade de casos de utilização, permitindo que os programadores se concentrem na lógica de negócio exclusiva, ao mesmo tempo que têm a certeza de que o Web PubSub oferece baixa latência (<100ms),elevada disponibilidade e dimensionamento maciço (milhões de ligações simultâneas).
Passos seguintes
No próximo passo, vamos explorar como trabalhar com o sistema de eventos do Web PubSub, necessário para criar aplicações Web completas.