Dela via

Rest API-referens för Azure SignalR Service-dataplan

  • Artikel

Utöver det klassiska klient-/servermönstret tillhandahåller Azure SignalR Service en uppsättning REST-API:er som hjälper dig att integrera realtidsfunktioner i din serverlösa arkitektur.

Kommentar

Azure SignalR Service stöder endast användning av REST-API:er för att hantera klienter som är anslutna via ASP.NET Core SignalR. Klienter som är anslutna via ASP.NET SignalR använder ett annat dataprotokoll som för närvarande inte stöds.

Typisk serverlös arkitektur med Azure Functions

Följande diagram visar en typisk serverlös arkitektur som använder Azure SignalR Service med Azure Functions.

Diagram över en typisk serverlös arkitektur för Azure SignalR Service.

  • Funktionen negotiate returnerar ett förhandlingssvar och omdirigerar alla klienter till Azure SignalR Service.
  • Funktionen broadcast anropar REST-API:et för Azure SignalR Service. Azure SignalR Service sänder meddelandet till alla anslutna klienter.

I en serverlös arkitektur har klienter beständiga anslutningar till Azure SignalR Service. Eftersom det inte finns någon programserver för att hantera trafik är klienterna i LISTEN läge. I det läget kan klienter ta emot meddelanden men kan inte skicka meddelanden. Azure SignalR Service kopplar från alla klienter som skickar meddelanden eftersom det är en ogiltig åtgärd.

Du hittar ett komplett exempel på hur du använder Azure SignalR Service med Azure Functions på den här GitHub-lagringsplatsen.

Implementera förhandlingsslutpunkten

Du bör implementera en negotiate funktion som returnerar ett omdirigeringsförhandlingssvar så att klienter kan ansluta till tjänsten.

Ett typiskt förhandlingssvar har följande format:

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

Värdet accessToken genereras via samma algoritm som beskrivs i autentiseringsavsnittet. Den enda skillnaden är att anspråket aud ska vara detsamma som url.

Du bör vara värd för ditt förhandlings-API så https://<hub_url>/negotiate att du fortfarande kan använda en SignalR-klient för att ansluta till hubb-URL:en. Läs mer om att omdirigera klienter till Azure SignalR Service i klientanslutningar.

REST API-versioner

I följande tabell visas alla REST API-versioner som stöds. Den innehåller även Swagger-filen för varje API-version.

API-version Status Port Dokumentation Specifikation
20220601 Senast Standard Artikel Swagger-fil
1.0 Stable Standard Artikel Swagger-fil
1.0-preview Föråldrad Standard Artikel Swagger-fil

I följande tabell visas tillgängliga API:er.

API Sökväg
Skicka ett meddelande till alla klienter som är anslutna till målhubben POST /api/v1/hubs/{hub}
Skicka ett meddelande till alla klienter som tillhör målanvändaren POST /api/v1/hubs/{hub}/users/{id}
Skicka meddelande till den specifika anslutningen POST /api/v1/hubs/{hub}/connections/{connectionId}
Kontrollera om anslutningen med det angivna connectionId:et finns GET /api/v1/hubs/{hub}/connections/{connectionId}
Stäng klientanslutningen DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Skicka ett meddelande till alla klienter i målgruppen POST /api/v1/hubs/{hub}/groups/{group}
Kontrollera om det finns några klientanslutningar i den angivna gruppen GET /api/v1/hubs/{hub}/groups/{group}
Kontrollera om det finns några anslutna klientanslutningar för den angivna användaren GET /api/v1/hubs/{hub}/users/{user}
Lägga till en anslutning till målgruppen PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Ta bort en anslutning från målgruppen DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Kontrollera om en användare finns i målgruppen GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Lägga till en användare i målgruppen PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Ta bort en användare från målgruppen DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Ta bort en användare från alla grupper DELETE /api/v1/hubs/{hub}/users/{user}/groups

Använda REST API

Autentisering via AccessKey i Azure SignalR Service

I varje HTTP-begäran krävs ett auktoriseringshuvud med en JSON-webbtoken (JWT) för att autentisera med Azure SignalR Service.

Signeringsalgoritm och signatur

HS256, nämligen HMAC-SHA256, används som signeringsalgoritm.

AccessKey Använd värdet i Azure SignalR Service-instansens anslutningssträng för att signera den genererade JWT.

Anspråk

Följande anspråk måste ingå i JWT.

Anspråkstyp Obligatoriskt beskrivning
aud true Måste vara samma som URL:en för HTTP-begäran, utan att inkludera de avslutande snedstrecks- och frågeparametrarna. En sändningsförfrågans målgrupp bör till exempel se ut så här: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Epoktid när denna token upphör att gälla.

Autentisering via Microsoft Entra-token

På samma sätt som att autentisera via AccessKeykrävs en JWT för att autentisera en HTTP-begäran med hjälp av en Microsoft Entra-token.

Skillnaden är att Microsoft Entra ID i det här scenariot genererar JWT. Mer information finns i Lär dig hur du genererar Microsoft Entra-token.

Omfånget för autentiseringsuppgifter ska vara https://signalr.azure.com/.default.

Du kan också använda rollbaserad åtkomstkontroll (RBAC) för att auktorisera begäran från klienten eller servern till Azure SignalR Service. Mer information finns i Auktorisera åtkomst med Microsoft Entra-ID för Azure SignalR Service.

Om du vill anropa det användarrelaterade REST-API:et bör var och en av dina klienter identifiera sig för Azure SignalR Service. Annars kan Azure SignalR Service inte hitta målanslutningar från användar-ID:t.

Du kan uppnå klientidentifiering genom att inkludera ett nameid anspråk i varje klients JWT när den ansluter till Azure SignalR Service. Azure SignalR Service använder sedan värdet för anspråket nameid som användar-ID för varje klientanslutning.

Exempel

På den här GitHub-lagringsplatsen hittar du en komplett konsolapp som visar hur du manuellt skapar en REST API HTTP-begäran i Azure SignalR Service.

Du kan också använda Microsoft.Azure.SignalR.Management för att publicera meddelanden till Azure SignalR Service med hjälp av IHubContextliknande gränssnitt för . Du hittar exempel på den här GitHub-lagringsplatsen. Mer information finns i Azure SignalR Service Management SDK.

Begränsningar

För närvarande har REST API-begäranden följande begränsningar:

  • Rubrikstorleken är högst 16 kB.
  • Brödtextstorleken är högst 1 MB.

Om du vill skicka meddelanden som är större än 1 MB använder du Service Management SDK med persistent läge.