Condividi tramite

Web PubSub SDK sul lato client per JavaScript

  • Articolo

Nota

I dettagli sui termini usati di seguito sono descritti nell'articolo concetti chiave.

L'SDK lato client mira a velocizzare il flusso di lavoro dello sviluppatore; più in particolare,

  • semplifica la gestione delle connessioni client
  • semplifica l'invio di messaggi tra i client
  • tentativi automatici dopo l'eliminazione imprevista della connessione client
  • recapita in modo affidabile i messaggi in numero e in ordine dopo il ripristino dall'eliminazione della connessione

Come illustrato nel diagramma, i client stabiliscono connessioni WebSocket con la risorsa Web PubSub.

Screenshot che mostra i client che stabiliscono una connessione WebSocket con una risorsa Web PubSub

Importante

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo.

Una stringa di connessione include le informazioni sull'autorizzazione necessarie all'applicazione per l'accesso al servizio Azure Web PubSub. La chiave di accesso all'interno della stringa di connessione è simile a una password radice per il servizio. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere la connessione con WebPubSubServiceClient.

Evitare di distribuire le chiavi di accesso ad altri utenti, impostarle come hardcoded o salvarle in un file di testo normale accessibile ad altri. Ruotare le chiavi se si ritiene che siano state compromesse.

Introduzione

Prerequisiti

1. Installare il @azure/web-pubsub-client pacchetto

npm install @azure/web-pubsub-client

2. Connettersi con la risorsa PubSub Web

Un client usa Client Access URL per connettersi ed eseguire l'autenticazione con il servizio, che segue un modello di wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Un client può avere alcuni modi per ottenere Client Access URL. Per questa guida rapida, è possibile copiarne e incollarne una da portale di Azure mostrata. Per l'ambiente di produzione, i client vengono Client Access URL in genere generati nel server applicazioni. Vedere i dettagli )

Screenshot che mostra come ottenere l'URL accesso client in portale di Azure

Come illustrato nel diagramma, il client dispone delle autorizzazioni per l'invio di messaggi a e l'aggiunta a un gruppo specifico denominato group1.

// Imports the client library
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Partecipare ai gruppi

Un client può ricevere messaggi solo dai gruppi aggiunti. È possibile aggiungere un callback per specificare la logica di cosa fare quando si ricevono messaggi.

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Inviare messaggi a un gruppo

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Esempi

Gestire connectedgli eventi e disconnected stopped

Web PubSub di Azure genera eventi di sistema come connected, disconnected e stopped. È possibile registrare i gestori eventi per decidere cosa deve fare il programma quando vengono generati gli eventi.

  1. Quando un client è connesso correttamente alla risorsa Web PubSub, l'evento connected viene attivato. Questo frammento di codice stampa semplicemente l'ID connessione
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Quando un client viene disconnesso e non riesce a recuperare la connessione, l'evento disconnected viene attivato. Questo frammento stampa semplicemente il messaggio.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. L'evento stopped viene attivato quando il client viene disconnesso e il client smette di tentare di riconnettersi. Ciò si verifica in genere dopo la client.stop() chiamata di o autoReconnect è disabilitato o viene raggiunto un limite specificato per il tentativo di riconnessione. Se si vuole riavviare il client, è possibile chiamare client.start() nell'evento arrestato.
// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Usare un server applicazioni per generare Client Access URL a livello di codice

Nell'ambiente di produzione, i client in genere recuperano Client Access URL da un server applicazioni. Il server contiene l'oggetto connection string alla risorsa PubSub Web e genera l'oggetto Client Access URL con la Guida dalla libreria @azure/web-pubsublato server .

1. Server applicazioni

Il frammento di codice è un esempio di un server applicazioni che espone un /negotiate endpoint e restituisce Client Access URL.

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere la connessione con WebPubSubServiceClient.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. Lato client

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Nota

Per visualizzare il codice completo di questo esempio, fare riferimento a samples-browser.

Un client utilizza messaggi dal server applicazioni o dai gruppi aggiunti

Un client può aggiungere callback per utilizzare messaggi da un server applicazioni o da gruppi.

// Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Nota

Per group-message l'evento, il client può ricevere solo messaggi dai gruppi aggiunti.

Gestire l'errore di ricongiuzione

Quando un client viene disconnesso e non riesce a eseguire il ripristino, tutti i contesti di gruppo vengono puliti nella risorsa Web PubSub. Ciò significa che quando il client si riconnette, deve riconnettersi ai gruppi. Per impostazione predefinita, il client ha autoRejoinGroup l'opzione abilitata.

Tuttavia, è necessario tenere presenti autoRejoinGrouple limitazioni.

  • Il client può riaggiungere i gruppi aggiunti dal codice client non dal codice lato server.
  • Le operazioni di "Gruppo di ricongiuni" potrebbero non riuscire a causa di diversi motivi, ad esempio il client non dispone dell'autorizzazione per l'aggiunta ai gruppi. In questi casi, è necessario aggiungere un callback per gestire questo errore.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

Riprova

Per impostazione predefinita, l'operazione, client.joinGroup()ad esempio , client.leaveGroup()client.sendToGroup(), , client.sendEvent() prevede tre tentativi. È possibile configurare tramite .messageRetryOptions Se tutti i tentativi non sono riusciti, viene generato un errore. È possibile continuare a ripetere i tentativi passando gli stessi ackId tentativi precedenti in modo che il servizio Web PubSub possa deduplicare l'operazione.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

JavaScript Bundle

Per usare questa libreria client nel browser, è necessario usare un bundler. Per informazioni dettagliate su come creare un bundle, vedere la documentazione di creazione di bundle.

Risoluzione dei problemi

Abilitare i log

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

export AZURE_LOG_LEVEL=verbose

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione sul pacchetto @azure/logger.

Traccia in tempo reale

Usare lo strumento Live Trace da portale di Azure per esaminare il traffico dei messaggi live attraverso la risorsa Web PubSub.