Delen via

Naslaginformatie over de REST API voor Azure SignalR Service-gegevensvlak

  • Artikel

Naast het klassieke client-/serverpatroon biedt Azure SignalR Service een set REST API's om u te helpen realtime functionaliteit te integreren in uw serverloze architectuur.

Notitie

Azure SignalR Service ondersteunt het gebruik van REST API's alleen voor het beheren van clients die zijn verbonden via ASP.NET Core SignalR. Clients die zijn verbonden via ASP.NET SignalR gebruiken een ander gegevensprotocol dat momenteel niet wordt ondersteund.

Typische serverloze architectuur met Azure Functions

In het volgende diagram ziet u een typische serverloze architectuur die gebruikmaakt van Azure SignalR Service met Azure Functions.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • De negotiate functie retourneert een onderhandelingsantwoord en stuurt alle clients om naar Azure SignalR Service.
  • De broadcast functie roept de REST API aan voor Azure SignalR Service. Azure SignalR Service verzendt het bericht naar alle verbonden clients.

In een serverloze architectuur hebben clients permanente verbindingen met Azure SignalR Service. Omdat er geen toepassingsserver is om verkeer te verwerken, bevinden clients zich in LISTEN de modus. In die modus kunnen clients berichten ontvangen, maar kunnen ze geen berichten verzenden. Azure SignalR Service verbreekt de verbinding met elke client die berichten verzendt omdat het een ongeldige bewerking is.

U vindt een volledig voorbeeld van het gebruik van Azure SignalR Service met Azure Functions in deze GitHub-opslagplaats.

Het onderhandelingseindpunt implementeren

U moet een negotiate functie implementeren die een omleidingsonderhandelingsreactie retourneert, zodat clients verbinding kunnen maken met de service.

Een typisch onderhandelingsantwoord heeft deze indeling:

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

De accessToken waarde wordt gegenereerd via hetzelfde algoritme dat wordt beschreven in de verificatiesectie. Het enige verschil is dat de aud claim gelijk moet zijn aan url.

U moet uw onderhandelings-API https://<hub_url>/negotiate hosten zodat u nog steeds een SignalR-client kunt gebruiken om verbinding te maken met de hub-URL. Lees meer over het omleiden van clients naar Azure SignalR Service in clientverbindingen.

REST API-versies

In de volgende tabel ziet u alle ondersteunde REST API-versies. Het biedt ook het Swagger-bestand voor elke API-versie.

API-versie Status Poort Documentatie Specificatie
20220601 Laatste Standaard Artikel Swagger-bestand
1.0 Stabiel Standaard Artikel Swagger-bestand
1.0-preview Verouderd Standaard Artikel Swagger-bestand

De volgende tabel bevat de beschikbare API's.

API Pad
Een bericht uitzenden naar alle clients die zijn verbonden met de doelhub POST /api/v1/hubs/{hub}
Een bericht uitzenden naar alle clients behoort tot de doelgebruiker POST /api/v1/hubs/{hub}/users/{id}
Bericht verzenden naar de specifieke verbinding POST /api/v1/hubs/{hub}/connections/{connectionId}
Controleer of de verbinding met de opgegeven connectionId bestaat GET /api/v1/hubs/{hub}/connections/{connectionId}
Sluit de clientverbinding DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Een bericht uitzenden naar alle clients binnen de doelgroep POST /api/v1/hubs/{hub}/groups/{group}
Controleer of er clientverbindingen in de opgegeven groep zijn GET /api/v1/hubs/{hub}/groups/{group}
Controleer of er clientverbindingen zijn verbonden voor de opgegeven gebruiker GET /api/v1/hubs/{hub}/users/{user}
Een verbinding toevoegen aan de doelgroep PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Een verbinding uit de doelgroep verwijderen DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Controleren of een gebruiker bestaat in de doelgroep GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Een gebruiker toevoegen aan de doelgroep PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Een gebruiker verwijderen uit de doelgroep DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Een gebruiker uit alle groepen verwijderen DELETE /api/v1/hubs/{hub}/users/{user}/groups

De REST API gebruiken

Verificatie via AccessKey in Azure SignalR Service

In elke HTTP-aanvraag is een autorisatieheader met een JSON-webtoken (JWT) vereist voor verificatie met Azure SignalR Service.

Handtekeningalgoritme en handtekening

HS256, namelijk HMAC-SHA256, wordt gebruikt als het ondertekeningsalgoritme.

Gebruik de AccessKey waarde in de verbindingsreeks van het Azure SignalR Service-exemplaar om de gegenereerde JWT te ondertekenen.

Claims

De volgende claims moeten worden opgenomen in de JWT.

Claimtype Is vereist Omschrijving
aud true Moet hetzelfde zijn als de URL van uw HTTP-aanvraag, niet inclusief de afsluitende slash- en queryparameters. De doelgroep van een broadcast-aanvraag moet er bijvoorbeeld als volgt uitzien: https://example.service.signalr.net/api/v1/hubs/myhub
exp true Tijdsduur waarop dit token verloopt.

Verificatie via Microsoft Entra-token

Net als bij verificatie via AccessKey, is een JWT vereist voor het verifiëren van een HTTP-aanvraag met behulp van een Microsoft Entra-token.

Het verschil is dat in dit scenario Microsoft Entra ID de JWT genereert. Zie Meer informatie over het genereren van Microsoft Entra-tokens.

U kunt ook op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om de aanvraag van uw client of server te autoriseren naar Azure SignalR Service. Zie Toegang autoriseren met Microsoft Entra ID voor Azure SignalR Service voor meer informatie.

Als u de gebruikersgerelateerde REST API wilt aanroepen, moet elk van uw clients zich identificeren bij Azure SignalR Service. Anders kan Azure SignalR Service geen doelverbindingen vinden vanuit de gebruikers-id.

U kunt clientidentificatie bereiken door een nameid claim op te geven in de JWT van elke client wanneer deze verbinding maakt met Azure SignalR Service. Azure SignalR Service gebruikt vervolgens de waarde van de nameid claim als de gebruikers-id voor elke clientverbinding.

Voorbeeld

In deze GitHub-opslagplaats vindt u een volledige console-app om te laten zien hoe u handmatig een REST API HTTP-aanvraag bouwt in Azure SignalR Service.

U kunt ook Microsoft.Azure.SignalR.Management gebruiken om berichten te publiceren naar Azure SignalR Service met behulp van de vergelijkbare interfaces van IHubContext. U vindt voorbeelden in deze GitHub-opslagplaats. Zie Azure SignalR Service Management SDK voor meer informatie.

Beperkingen

Momenteel hebben REST API-aanvragen de volgende beperkingen:

  • De koptekstgrootte is maximaal 16 kB.
  • De grootte van de hoofdtekst is maximaal 1 MB.

Als u berichten wilt verzenden die groter zijn dan 1 MB, gebruikt u de Service Management SDK met persistent de modus.