Share via

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

  • Artigo

Além do padrão cliente/servidor clássico, o Serviço SignalR do Azure 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 Azure SignalR dá suporte ao uso de APIs REST somente para gerenciar clientes conectados por meio do ASP.NET Core SignalR. Os clientes conectados por meio ASP.NET SignalR usam um protocolo de dados diferente que não é suportado no momento.

Arquitetura típica sem servidor 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 SignalR do Azure.
  • A broadcast função chama a API REST para o Serviço SignalR do Azure. 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 SignalR do Azure. Como não há 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 de como usar o Serviço SignalR do Azure 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 por meio do mesmo algoritmo descrito na seção de autenticação. A única diferença é que a alegação deve ser a aud mesma que url.

Você deve hospedar sua API de negociação para que ainda possa usar um cliente SignalR para https://<hub_url>/negotiate se conectar à URL do hub. Leia mais sobre como redirecionar clientes para o Serviço SignalR do Azure 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 Obsoleta Standard Artigo Arquivo do 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 pertencentes ao usuário de destino POST /api/v1/hubs/{hub}/users/{id}
Enviar mensagem para a conexão específica POST /api/v1/hubs/{hub}/connections/{connectionId}
Verificar se a conexão com a connectionId determinada existe GET /api/v1/hubs/{hub}/connections/{connectionId}
Fechar conexão de cliente DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Transmitir uma mensagem para todos os clientes dentro do grupo de destino POST /api/v1/hubs/{hub}/groups/{group}
Verificar se há conexões de cliente dentro do grupo determinado GET /api/v1/hubs/{hub}/groups/{group}
Verificar se há conexões de cliente conectadas para o usuário determinado GET /api/v1/hubs/{hub}/users/{user}
Adicionar uma conexão ao grupo de destino PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Remover uma conexão do grupo de destino DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Verificar se um usuário existe no grupo de destino GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Adicionar um usuário ao grupo de destino PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remover um usuário do grupo de destino DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remover um usuário de todos os grupos DELETE /api/v1/hubs/{hub}/users/{user}/groups

Usando 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 SignalR do Azure.

Algoritmo de assinatura e assinatura

HS256, a saber, HMAC-SHA256, é usado como o algoritmo de assinatura.

Use o valor na cadeia de conexão da instância do Serviço SignalR do Azure para assinar o AccessKey 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 igual à URL da 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 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 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 RBAC (controle de acesso baseado em função) para autorizar a solicitação do seu cliente ou servidor para o Serviço SignalR do Azure. 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 de seus clientes deve se identificar no Serviço SignalR do Azure. Caso contrário, o Serviço SignalR do Azure não poderá localizar 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 SignalR do Azure. Em seguida, o Serviço Azure SignalR usa o nameid valor da declaração como a ID do usuário para cada conexão de cliente.

Amostra

Neste repositório do 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 do 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 é de no máximo 1 MB.

Se você quiser enviar mensagens maiores que 1 MB, use o modo Service Management SDK com persistent .