NOTE
Azure SignalR Service only supports REST API for ASP.NET CORE SignalR applications.
On top of classical client-server pattern, Azure SignalR Service provides a set of REST APIs, so that you can easily integrate real-time functionality into your server-less architecture.
The following diagram shows a typical server-less architecture of using Azure SignalR Service with Azure Functions.
negotiate
function will return negotiation response and redirect all clients to Azure SignalR Service.broadcast
function will call Azure SignalR Service's REST API. Then SignalR Service will broadcast the message to all connected clients.
In server-less architecture, clients still have persistent connections to Azure SignalR Service.
Since there are no application server to handle traffic, clients are in LISTEN
mode, which means they can only receive messages but can't send messages.
SignalR Service will disconnect any client who sends messages because it is an invalid operation.
NOTE: In version 1.1.0-preview of ASP.NET Core SignalR, client will send
PingMessage
to server. Right now it will cause SignalR Service disconnecting clients. So the latest 1.0.x version of ASP.NET Core SignalR client library is recommended to use with Azure SignalR Service. We are working in progress to support the new version of ASP.NET Core SignalR.
You can find a complete sample of using Azure SignalR Service with Azure Functions at here.
The following table shows all versions of REST API we have for now. You can also find the swagger file for each version of REST API.
API Version | Status | Port | Spec |
---|---|---|---|
1.0-preview |
Available | 5002 | swagger |
1.0 |
Not Available until GA | Standard | swagger |
Available APIs of each version are listed as following.
API | 1.0-preview |
1.0 |
---|---|---|
Broadcast to all | ✔️ | ✔️ |
Broadcast to a group | ✔️ | ✔️ |
Broadcast to a few groups | ✔️ (Deprecated) | N/A |
Send to a user | ✔️ | ✔️ |
Send to a few users | ✔️ (Deprecated) | N/A |
Add a user to a group | N/A |
✔️ |
Remove a user from a group | N/A |
✔️ |
API Version | HTTP Method | Request URL | Request Body |
---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name> |
{ "target":"<method-name>", "arguments":[ ... ] } |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name> |
Same as above |
API Version | HTTP Method | Request URL | Request Body |
---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/group/<group-name> |
{ "target":"<method-name>", "arguments":[ ... ] } |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name> |
Same as above |
API Version | HTTP Method | Request URL | Request Body |
---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/user/<user-id> |
{ "target":"<method-name>", "arguments":[ ... ] } |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id> |
Same as above |
API Version | HTTP Method | Request URL |
---|---|---|
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
API Version | HTTP Method | Request URL |
---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
In each HTTP request, an authorization header with a JSON Web Token (JWT) is required to authenticate with Azure SignalR Service.
HS256
, namely HMAC-SHA256, is used as the signing algorithm.
You should use the AccessKey
in Azure SignalR Service instance's connection string to sign the generated JWT token.
Below claims are required to be included in the JWT token.
Claim Type | Is Required | Description |
---|---|---|
aud |
true | Should be the SAME as your HTTP request url, trailing slash and query paramters not included. For example, a broadcast request's audience should look like: https://example.service.signalr.net/api/v1/hubs/myhub . |
exp |
true | Epoch time when this token will be expired. |
In order to call user-related REST API, each of your clients should identify themselves to Azure SignalR Service. Otherwise SignalR Service can't find target connections from a given user id.
This can be achieved by including a nameid
claim in each client's JWT token when they are connecting to Azure SignalR Service.
Then SignalR Service will use the value of nameid
claim as the user id of each client connection.
As shown in the architecture section, the negotiate
function will return a redirect negotiation response to client.
A typical negotiation response looks like as folllowing. The nameid
claim should be included in the access token.
```json
{
"url":"https://test.service.signalr.net:5001/client/?hub=chat&...",
"accessToken":"<a typical JWT token>"
}
```
Read more about redirecting client to Azure SignalR Service at here.
You can find a complete console app to demonstrate how to use REST API in Azure SignalR Service at here.