Referência da API REST do plano de dados do Serviço do Azure SignalR
Além do padrão clássico de cliente/servidor, o Serviço Azure SignalR fornece um conjunto de APIs REST para ajudá-lo a integrar a funcionalidade em tempo real à sua arquitetura sem servidor.
Observação
O Serviço do Azure SignalR dá suporte ao uso de APIs REST apenas para gerenciar clientes conectados por meio ASP.NET Core SignalR. Os clientes conectados por meio do ASP.NET SignalR usam um protocolo de dados diferente que não tem suporte no momento.
Arquitetura sem servidor típica com o Azure Functions
O diagrama a seguir mostra uma arquitetura sem servidor típica que usa o Serviço do Azure SignalR com o Azure Functions.
- A
negotiatefunção retorna uma resposta de negociação e redireciona todos os clientes para o Serviço do Azure SignalR. - A
broadcastfunção chama a API REST para o Serviço do Azure SignalR. O Serviço do Azure SignalR transmite a mensagem para todos os clientes conectados.
Em uma arquitetura sem servidor, os clientes têm conexões persistentes com o Serviço do Azure SignalR. Como não há nenhum servidor de aplicativos para lidar com o tráfego, os clientes estão no LISTEN modo. Nesse modo, os clientes podem receber mensagens, mas não podem enviar mensagens. O Serviço do Azure SignalR desconecta qualquer cliente que envia mensagens porque é uma operação inválida.
Você pode encontrar um exemplo completo de como usar o Serviço do Azure SignalR com o Azure Functions neste repositório do GitHub.
Implementar o ponto de extremidade de negociação
Você deve implementar uma negotiate função que retorne uma resposta de negociação de redirecionamento para que os clientes possam se conectar ao serviço.
Uma resposta de negociação típica tem este formato:
{
"url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
"accessToken": "<a typical JWT token>"
}
O accessToken valor é gerado por meio do mesmo algoritmo descrito na seção de autenticação. A única diferença é que a aud afirmação deve ser a mesma que url.
Você deve hospedar sua API de negociação para https://<hub_url>/negotiate que ainda possa usar um cliente SignalR para se conectar à URL do hub. Leia mais sobre como redirecionar clientes para o Serviço do Azure SignalR em conexões de cliente.
Versões de API REST
A tabela a seguir mostra todas as versões da API REST com suporte. Ele também fornece o arquivo Swagger para cada versão da API.
| Versão da API | Status | Porta | Documentação | Especificação |
|---|---|---|---|---|
20220601 |
Mais recente | Standard | Artigo | Arquivo do Swagger |
1.0 |
Estável | Standard | Artigo | Arquivo do Swagger |
1.0-preview |
Obsoleto | Standard | Artigo | Arquivo do Swagger |
A tabela a seguir lista as APIs disponíveis.
Usando a API REST
Autenticação por meio de AccessKey no Serviço do Azure SignalR
Em cada solicitação HTTP, um cabeçalho de autorização com um JWT (Token Web JSON) é necessário para autenticar com o Serviço do Azure SignalR.
Algoritmo de assinatura e assinatura
HS256, a saber, HMAC-SHA256, é usado como o algoritmo de assinatura.
Use o AccessKey valor na cadeia de conexão da instância do Serviço do Azure SignalR para assinar o JWT gerado.
Declarações
As seguintes reivindicações devem ser incluídas no JWT.
| Tipo de declaração | É obrigatório | Descrição |
|---|---|---|
aud |
true |
Precisa ser o mesmo que o URL da solicitação HTTP, sem incluir a barra final e os parâmetros de consulta. Por exemplo, o público de uma solicitação de transmissão deve ser semelhante a: https://example.service.signalr.net/api/v1/hubs/myhub. |
exp |
true |
Hora da época em que esse token expira. |
Autenticação via token do Microsoft Entra
Semelhante à autenticação via AccessKey, um JWT é necessário para autenticar uma solicitação HTTP usando um token do Microsoft Entra.
A diferença é que, nesse cenário, a ID do Microsoft Entra gera o JWT. Para obter mais informações, consulte Saiba como gerar tokens do Microsoft Entra.
O escopo de credencial usado deve ser https://signalr.azure.com/.default.
Você também pode usar o RBAC (controle de acesso baseado em função) para autorizar a solicitação do cliente ou servidor para o Serviço do Azure SignalR. Para obter mais informações, consulte Autorizar o acesso com a ID do Microsoft Entra para o Serviço do Azure SignalR.
API REST relacionada ao usuário
Para chamar a API REST relacionada ao usuário, cada um de seus clientes deve se identificar para o Serviço do Azure SignalR. Caso contrário, o Serviço do Azure SignalR não poderá encontrar conexões de destino da ID do usuário.
Você pode obter a identificação do cliente incluindo uma nameid declaração no JWT de cada cliente quando ele estiver se conectando ao Serviço do Azure SignalR. O Serviço do Azure SignalR usa o valor da declaração como a ID do nameid usuário para cada conexão do cliente.
Amostra
Neste repositório GitHub, você pode encontrar um aplicativo de console completo para demonstrar como criar manualmente uma solicitação HTTP da API REST no Serviço do Azure SignalR.
Você também pode usar Microsoft.Azure.SignalR.Management para publicar mensagens no Serviço do Azure SignalR usando as interfaces semelhantes do IHubContext. Você pode encontrar exemplos neste repositório GitHub. Para obter mais informações, consulte SDK de Gerenciamento de Serviços do Azure SignalR.
Limitações
Atualmente, as solicitações da API REST têm as seguintes limitações:
- O tamanho do cabeçalho é de no máximo 16 KB.
- O tamanho do corpo é de no máximo 1 MB.
Se você quiser enviar mensagens maiores que 1 MB, use o SDK do Gerenciamento de Serviços com persistent modo.