Informazioni di riferimento sulle API REST del piano dati Servizio Azure SignalR

  • Articolo

Oltre al modello client/server classico, Servizio Azure SignalR fornisce un set di API REST che consentono di integrare funzionalità in tempo reale nell'architettura serverless.

Nota

Servizio Azure SignalR supporta l'uso delle API REST solo per gestire i client connessi tramite ASP.NET Core SignalR. I client connessi tramite ASP.NET SignalR usano un protocollo dati diverso attualmente non supportato.

Architettura serverless tipica con Funzioni di Azure

Il diagramma seguente illustra un'architettura serverless tipica che usa Servizio Azure SignalR con Funzioni di Azure.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • La negotiate funzione restituisce una risposta di negoziazione e reindirizza tutti i client a Servizio Azure SignalR.
  • La broadcast funzione chiama l'API REST per Servizio Azure SignalR. Servizio Azure SignalR trasmette il messaggio a tutti i client connessi.

In un'architettura serverless i client dispongono di connessioni permanenti a Servizio Azure SignalR. Poiché non è disponibile alcun server applicazioni per gestire il traffico, i client sono in LISTEN modalità . In tale modalità, i client possono ricevere messaggi, ma non possono inviare messaggi. Servizio Azure SignalR disconnette tutti i client che inviano messaggi perché si tratta di un'operazione non valida.

È possibile trovare un esempio completo dell'uso di Servizio Azure SignalR con Funzioni di Azure in questo repository GitHub.

Implementare l'endpoint di negoziazione

È necessario implementare una funzione che restituisce una negotiate risposta di negoziazione di reindirizzamento in modo che i client possano connettersi al servizio.

Una tipica risposta di negoziazione ha questo formato:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

Il accessToken valore viene generato tramite lo stesso algoritmo descritto nella sezione relativa all'autenticazione. L'unica differenza è che l'attestazione aud deve essere uguale urla .

È consigliabile ospitare l'API di negoziazione in https://<hub_url>/negotiate per poter comunque usare un client SignalR per connettersi all'URL dell'hub. Altre informazioni sul reindirizzamento dei client alle Servizio Azure SignalR in Connessioni client.

Versioni dell'API REST

La tabella seguente mostra tutte le versioni dell'API REST supportate. Fornisce anche il file Swagger per ogni versione dell'API.

Versione dell'API Stato Port Documentazione Specifica
20220601 Più recente Standard Articolo File Swagger
1.0 Stable Standard Articolo File Swagger
1.0-preview Obsoleto Standard Articolo File Swagger

Nella tabella seguente sono elencate le API disponibili.

API Percorso
Trasmettere un messaggio a tutti i client connessi all'hub di destinazione POST /api/v1/hubs/{hub}
Trasmettere un messaggio a tutti i client appartengono all'utente di destinazione POST /api/v1/hubs/{hub}/users/{id}
Inviare un messaggio alla connessione specifica POST /api/v1/hubs/{hub}/connections/{connectionId}
Controllare se la connessione con l'id connessione specificato esiste GET /api/v1/hubs/{hub}/connections/{connectionId}
Chiudere la connessione client DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Trasmettere un messaggio a tutti i client all'interno del gruppo di destinazione POST /api/v1/hubs/{hub}/groups/{group}
Controllare se sono presenti connessioni client all'interno del gruppo specificato GET /api/v1/hubs/{hub}/groups/{group}
Controllare se sono presenti connessioni client connesse per l'utente specificato GET /api/v1/hubs/{hub}/users/{user}
Aggiungere una connessione al gruppo di destinazione PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Rimuovere una connessione dal gruppo di destinazione DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Controllare se un utente esiste nel gruppo di destinazione GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Aggiungere un utente al gruppo di destinazione PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Rimuovere un utente dal gruppo di destinazione DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Rimuovere un utente da tutti i gruppi DELETE /api/v1/hubs/{hub}/users/{user}/groups

Tramite l'API REST

Autenticazione tramite AccessKey in Servizio Azure SignalR

In ogni richiesta HTTP è necessaria un'intestazione di autorizzazione con un token JSON Web (JWT) per l'autenticazione con Servizio Azure SignalR.

Algoritmo di firma e firma

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

Usare il AccessKey valore nel stringa di connessione dell'istanza di Servizio Azure SignalR per firmare il token JWT generato.

Richieste di rimborso

Le attestazioni seguenti devono essere incluse nel token JWT.

Tipo di attestazione Obbligatorio Descrizione
aud true Deve essere uguale all'URL della richiesta HTTP, senza includere i parametri di query e barra finale. Ad esempio, il pubblico di una richiesta di trasmissione dovrebbe essere simile al seguente: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Periodo di scadenza del token.

Autenticazione tramite token Microsoft Entra

Analogamente all'autenticazione tramite AccessKey, è necessario un token JWT per autenticare una richiesta HTTP usando un token Microsoft Entra.

La differenza è che in questo scenario, Microsoft Entra ID genera il token JWT. Per altre informazioni, vedere Informazioni su come generare token Microsoft Entra.

È anche possibile usare il controllo degli accessi in base al ruolo per autorizzare la richiesta dal client o dal server a Servizio Azure SignalR. Per altre informazioni, vedere Autorizzare l'accesso con Microsoft Entra ID per Servizio Azure SignalR.

Per chiamare l'API REST correlata all'utente, ognuno dei client deve identificarsi per Servizio Azure SignalR. In caso contrario, Servizio Azure SignalR non riesce a trovare le connessioni di destinazione dall'ID utente.

È possibile ottenere l'identificazione del client includendo un'attestazione nameid nel token JWT di ogni client quando si connette a Servizio Azure SignalR. Servizio Azure SignalR quindi usa il valore dell'attestazione nameid come ID utente per ogni connessione client.

Esempio

In questo repository GitHub è possibile trovare un'app console completa per illustrare come compilare manualmente una richiesta HTTP dell'API REST in Servizio Azure SignalR.

È anche possibile usare Microsoft.Azure.SignalR.Management per pubblicare messaggi in Servizio Azure SignalR usando le interfacce simili di IHubContext. Gli esempi sono disponibili in questo repository GitHub. Per altre informazioni, vedere Servizio Azure SignalR Management SDK.

Limiti

Attualmente, le richieste api REST presentano le limitazioni seguenti:

  • Le dimensioni dell'intestazione sono massime di 16 KB.
  • La dimensione del corpo è un massimo di 1 MB.

Se si desidera inviare messaggi di dimensioni superiori a 1 MB, usare Service Management SDK con persistent la modalità .