Referência da API REST do plano de dados do Serviço Azure SignalR

  • Artigo

Além do padrão clássico 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.

Nota

O Serviço Azure SignalR dá suporte ao uso de APIs REST apenas para gerenciar clientes conectados por meio do ASP.NET Core SignalR. Os clientes conectados através do ASP.NET SignalR usam um protocolo de dados diferente que não é suportado atualmente.

Arquitetura sem servidor típica com o Azure Functions

O diagrama a seguir mostra uma arquitetura típica sem servidor que usa o Serviço SignalR do Azure com o Azure Functions.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • A negotiate função retorna uma resposta de negociação e redireciona todos os clientes para o Serviço Azure SignalR.
  • A broadcast função chama a API REST para o Serviço Azure SignalR. O Serviço SignalR do Azure transmite a mensagem para todos os clientes conectados.

Em uma arquitetura sem servidor, os clientes têm conexões persistentes com o Serviço Azure SignalR. Como não há um 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 Azure SignalR desconecta qualquer cliente que envia mensagens porque é uma operação inválida.

Você pode encontrar um exemplo completo do uso do Serviço Azure SignalR com o Azure Functions neste repositório do GitHub.

Implementar o ponto de extremidade de negociação

Você deve implementar uma função que retorna uma negotiate 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 através do mesmo algoritmo descrito na seção de autenticação. A única diferença é que a reivindicação deve ser a aud mesma urlque .

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 Azure SignalR em conexões de cliente.

Versões da API REST

A tabela a seguir mostra todas as versões suportadas da API REST. Ele também fornece o arquivo Swagger para cada versão da API.

Versão da API Estado Porta Documentação Especificação
20220601 Mais Recente Standard Artigo Arquivo Swagger
1.0 Estável Standard Artigo Arquivo Swagger
1.0-preview Obsoleto Standard Artigo Arquivo Swagger

A tabela a seguir lista as APIs disponíveis.

API Caminho
Transmitir uma mensagem para todos os clientes conectados ao hub de destino POST /api/v1/hubs/{hub}
Transmitir uma mensagem para todos os clientes pertencem ao usuário alvo POST /api/v1/hubs/{hub}/users/{id}
Enviar mensagem para a conexão específica POST /api/v1/hubs/{hub}/connections/{connectionId}
Verifique se a conexão com o connectionId fornecido existe GET /api/v1/hubs/{hub}/connections/{connectionId}
Feche a conexão do cliente DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Transmitir uma mensagem a todos os clientes dentro do grupo-alvo POST /api/v1/hubs/{hub}/groups/{group}
Verifique se há alguma conexão de cliente dentro de um determinado grupo GET /api/v1/hubs/{hub}/groups/{group}
Verifique se há alguma conexão de cliente conectada para um determinado usuário GET /api/v1/hubs/{hub}/users/{user}
Adicionar uma ligação ao grupo-alvo PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Remover uma ligação do grupo-alvo DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Verificar se existe um utilizador no grupo-alvo GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Adicionar um utilizador ao grupo-alvo PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remover um utilizador do grupo-alvo DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remover um utilizador de todos os grupos DELETE /api/v1/hubs/{hub}/users/{user}/groups

Utilizar a API REST

Autenticação via AccessKey no Serviço Azure SignalR

Em cada solicitação HTTP, um cabeçalho de autorização com um JSON Web Token (JWT) é necessário para autenticar com o Serviço Azure SignalR.

Algoritmo de assinatura e assinatura

HS256, ou seja, HMAC-SHA256, é usado como o algoritmo de assinatura.

Use o valor na cadeia de conexão da instância do Serviço Azure SignalR para assinar o AccessKey JWT gerado.

Pedidos

As seguintes reivindicações devem ser incluídas no JWT.

Tipo de afirmação É obrigatório Descrição
aud true Precisa ser o mesmo que sua URL de solicitação HTTP, não incluindo a barra à direita e os parâmetros de consulta. Por exemplo, o público de uma solicitação de transmissão deve se parecer com: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Época em que este token expira.

Autenticação via token Microsoft Entra

Semelhante à autenticação via AccessKey, um JWT é necessário para autenticar uma solicitação HTTP usando um token Microsoft Entra.

A diferença é que, nesse cenário, o Microsoft Entra ID gera o JWT. Para obter mais informações, consulte Saiba como gerar tokens do Microsoft Entra.

Você também pode usar o controle de acesso baseado em função (RBAC) para autorizar a solicitação do seu cliente ou servidor para o Serviço Azure SignalR. Para obter mais informações, consulte Autorizar acesso com o Microsoft Entra ID para o Serviço Azure SignalR.

Para chamar a API REST relacionada ao usuário, cada um dos seus clientes deve se identificar no Serviço Azure SignalR. Caso contrário, o Serviço Azure SignalR não poderá encontrar conexões de destino a partir 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 Azure SignalR. Em seguida, o nameid Serviço SignalR do Azure usa o valor da declaração como a ID do usuário para cada conexão de cliente.

Exemplo

Neste repositório GitHub, você pode encontrar um aplicativo de console completo para demonstrar como criar manualmente uma solicitação REST API HTTP no Serviço Azure SignalR.

Você também pode usar Microsoft.Azure.SignalR.Management para publicar mensagens no Serviço 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ço do Azure SignalR.

Limitações

Atualmente, as solicitações de API REST têm as seguintes limitações:

  • O tamanho do cabeçalho é de no máximo 16 KB.
  • O tamanho do corpo é no máximo 1 MB.

Se você quiser enviar mensagens maiores que 1 MB, use o SDK de gerenciamento de serviços com persistent o modo.