Condividi tramite

Libreria client del servizio Web PubSub di Azure per JavaScript - versione 1.2.0

Il servizio Web PubSub di Azure è un servizio gestito di Azure che consente agli sviluppatori di creare facilmente applicazioni Web con funzionalità in tempo reale e modello di pubblicazione-sottoscrizione. Qualsiasi scenario che richiede la messaggistica di pubblicazione-sottoscrizione in tempo reale tra server e client o tra i client può usare il servizio Web PubSub di Azure. Le funzionalità tradizionali in tempo reale che spesso richiedono il polling dal server o l'invio di richieste HTTP possono usare anche il servizio PubSub Web di Azure.

È possibile usare questa libreria sul lato server dell'app per gestire le connessioni client WebSocket, come illustrato nel diagramma seguente:

trabocco .

  • Inviare messaggi a hub e gruppi.
  • Inviare messaggi a utenti e connessioni specifici.
  • Organizzare utenti e connessioni in gruppi.
  • Chiudere le connessioni
  • Concedere, revocare e controllare le autorizzazioni per una connessione esistente

I dettagli sui termini utilizzati qui sono descritti nella sezione Concetti chiave .

Codice sorgente | Pacchetto (NPM) | Documentazione | Documentazione del | prodottoCampioni

Introduttiva

Ambienti attualmente supportati

Prerequisiti

1. Installare il pacchetto @azure/web-pubsub

npm install @azure/web-pubsub

2. Creare ed autenticare un WebPubSubServiceClient

import { WebPubSubServiceClient } from "@azure/web-pubsub";

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

È inoltre possibile autenticare utilizzando WebPubSubServiceClient un endpoint e un AzureKeyCredential:

import { AzureKeyCredential, WebPubSubServiceClient } from "@azure/web-pubsub";

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Oppure autenticare il WebPubSubServiceClient utilizzando Azure Active Directory

  1. Installare la @azure/identity dipendenza
npm install @azure/identity
  1. Aggiornare il codice sorgente per utilizzare DefaultAzureCredential:
import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Concetti chiave

Connessione

Una connessione, nota anche come client o connessione client, rappresenta una singola connessione WebSocket connessa al servizio Web PubSub. Una volta stabilita la connessione, un ID di connessione univoco viene assegnato a questa connessione dal servizio Web PubSub.

Mozzo

Un hub è un concetto logico per un set di connessioni client. In genere si usa un hub per uno scopo, ad esempio un hub di chat o un hub di notifica. Quando viene creata una connessione client, si connette a un hub e, durante la sua durata, appartiene a tale hub. Diverse applicazioni possono condividere un servizio PubSub Web di Azure usando nomi di hub diversi.

Gruppo

Un gruppo è un subset di connessioni all'hub. È possibile aggiungere una connessione client a un gruppo o rimuovere la connessione client dal gruppo in qualsiasi momento. Ad esempio, quando un client si unisce a una chat room o quando un client lascia la chat room, questa chat room può essere considerata un gruppo. Un client può partecipare a più gruppi e un gruppo può contenere più client.

Utente

Le connessioni a Web PubSub possono appartenere a un utente. Un utente potrebbe avere più connessioni, ad esempio quando un singolo utente è connesso tra più dispositivi o più schede del browser.

Messaggio

Quando il client è connesso, può inviare messaggi all'applicazione upstream o ricevere messaggi dall'applicazione upstream tramite la connessione WebSocket.

Esempi

Ottenere il token di accesso per un client per avviare la connessione WebSocket

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: ["GroupA"] });

Trasmettere messaggi a tutte le connessioni in un hub

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

Inviare messaggi a tutte le connessioni in un hub con la sintassi del filtro OData

Per informazioni dettagliate sulla filter sintassi, vedere Sintassi del filtro OData per Azure Web PubSub.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message to anonymous connections
await serviceClient.sendToAll({ message: "Hello world!" }, { filter: "userId eq null" });

// Send a text message to connections in groupA but not in groupB
const groupA = "groupA";
const groupB = "groupB";
await serviceClient.sendToAll("Hello world!", {
  contentType: "text/plain",
  // use plain text "'groupA' in groups and not('groupB' in groups)"
  // or use the odata helper method
  filter: odata`${groupA} in groups and not(${groupB} in groups)`,
});

Inviare messaggi a tutte le connessioni in un gruppo

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Inviare messaggi a tutte le connessioni per un utente

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Controllare se il gruppo dispone di una connessione

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

Accedere alla risposta HTTP non elaborata per un'operazione

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Risoluzione dei problemi

Abilitare i log

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info.

export AZURE_LOG_LEVEL=verbose

In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Traccia in tempo reale

Utilizzare Live Trace dal portale del servizio Web PubSub per visualizzare il traffico in tempo reale.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere gli esempi di directory.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.