Informazioni di riferimento sulle API REST del piano dati del piano dati di Pubblicazione Web di Azure

Articolo
12/12/2024

Diagramma che mostra il flusso di lavoro del servizio Web PubSub.

Come illustrato dal grafico del flusso di lavoro precedente e anche dal flusso di lavoro dettagliato descritto in internals, il server app può inviare messaggi ai client o gestire i client connessi usando le API REST esposte dal servizio Web PubSub. Questo articolo descrive in dettaglio le API REST.

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.

Uso dell'API REST

Eseguire l'autenticazione tramite AccessKey del servizio Web PubSub di Azure

In ogni richiesta HTTP, è necessaria un'intestazione di autorizzazione con un token JSON Web (JWT) per l'autenticazione con il servizio PubSub Web di Azure.

Algoritmo di firma e firma

HS256, ovvero HMAC-SHA256, viene usato come algoritmo di firma.

È consigliabile usare nel AccessKey stringa di connessione dell'istanza del servizio Web PubSub di Azure per firmare il token JWT generato.

Richieste

Le attestazioni seguenti devono essere incluse nel token JWT.

Tipo di attestazione	Obbligatorio	Descrizione
`aud`	vero	Deve essere uguale all'URL della richiesta HTTP. Ad esempio, il pubblico di una richiesta di trasmissione è simile al seguente: `https://example.webpubsub.azure.com/api/hubs/myhub/:send?api-version=2022-11-01`.
`exp`	true	Periodo di tempo in cui questo token sarà scaduto.

Uno pseudo-codice in JS:

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.

const bearerToken = jwt.sign({}, connectionString.accessKey, {
  audience: request.url,
  expiresIn: "1h",
  algorithm: "HS256",
});

Eseguire l'autenticazione tramite il token Microsoft Entra

Analogamente all'uso AccessKeydi , è necessario anche un token JSON Web (JWT) per autenticare la richiesta HTTP.

La differenza è che, in questo scenario, il token JWT viene generato dall'ID Microsoft Entra.

Informazioni su come generare token Microsoft Entra

L'ambito delle credenziali usato deve essere https://webpubsub.azure.com/.default.

È anche possibile usare il controllo degli Controllo di accesso accessi in base al ruolo (RBAC) per autorizzare la richiesta dal server al servizio Web PubSub di Azure.

Informazioni su come configurare i ruoli di Controllo di accesso basati sui ruoli per la risorsa

API

Gruppo di operazioni	Descrizione
Stato del servizio	Fornisce operazioni per controllare lo stato del servizio
Operazioni dell'hub	Fornisce operazioni per gestire le connessioni e inviare messaggi.

Condividi tramite