Pontos de extremidade upstream

  • Artigo

O recurso de pontos de extremidade upstream permite que o Serviço SignalR do Azure envie mensagens e eventos de conexão para um conjunto de pontos de extremidade no modo sem servidor. Você pode usar pontos de extremidade upstream para invocar um método de hub de clientes no modo sem servidor para notificar pontos de extremidade quando as conexões de cliente estiverem conectadas ou desconectadas.

Observação

Os pontos de extremidade upstream só podem ser configurados no modo sem servidor.

Configurações de ponto de extremidade upstream

As configurações de um ponto de extremidade upstream consistem em uma lista de itens sensíveis ao pedido:

  • Um modelo de URL que especifica para onde as mensagens são enviadas.
  • Um conjunto de regras.
  • Configurações de autenticação.

Quando um evento é acionado, as regras de um item são verificadas uma a uma na ordem. As mensagens serão enviadas para a URL do ponto de extremidade upstream do primeiro item correspondente.

Configurações de modelo de URL

Você pode parametrizar a URL do ponto de extremidade upstream para oferecer suporte a vários padrões. Há três parâmetros predefinidos obrigatórios:

Parâmetro predefinido Descrição
{hub} Um hub é um conceito do Serviço do Azure SignalR. Um hub é uma unidade de isolamento. O escopo de usuários e a entrega de mensagens é restrito a um Hub.
{categoria} Uma categoria pode ser um dos seguintes valores:
  • conexões: eventos de tempo de vida da conexão. É acionado quando uma conexão do cliente é conectada ou desconectada. Inclui eventos conectados e desconectados.
  • mensagens: acionado quando os clientes invocam um método de hub. Ele inclui todos os outros eventos, exceto eventos na categoria conexões .
{evento} Na categoria mensagens, o evento é o destino em uma mensagem de invocação que os clientes enviam. Na categoria conexões, somente os valores conectado e desconectado são usados.

Esses parâmetros predefinidos podem ser usados no padrão de URL. Os parâmetros serão substituídos por um valor especificado quando você estiver avaliando a URL do ponto de extremidade upstream. Por exemplo:

http://host.com/{hub}/api/{category}/{event}

Quando uma conexão do cliente no hub de "chat" estiver conectada, uma mensagem será enviada a esta URL:

http://host.com/chat/api/connections/connected

Quando um cliente no hub de "chat" invocar o método de hub broadcast, uma mensagem será enviada para esta URL:

http://host.com/chat/api/messages/broadcast

Referência de segredo do Key Vault em configurações de modelo de URL

A URL do ponto de extremidade upstream não é criptografada. Você pode proteger pontos de extremidade upstream confidenciais usando o Cofre de Chaves e acessá-los com uma identidade gerenciada.

Para habilitar a identidade gerenciada em sua instância de serviço do SignalR e conceder a ela acesso ao Cofre de Chaves:

  1. Escolha uma identidade atribuída pelo sistema ou pelo usuário. Consulte Como adicionar identidade gerenciada no portal do Azure.

  2. Conceda permissão de leitura secreta para a identidade gerenciada nas políticas de acesso no Key Vault. Confira Atribuir uma política de acesso do Key Vault usando o portal do Azure

  3. Substitua seu texto confidencial pela sintaxe abaixo no padrão de URL do ponto de extremidade upstream:

    {@Microsoft.KeyVault(SecretUri=<secret-identity>)}

    O <secret-identity> deve ser o URI do plano de dados completo de um segredo no Key Vault, opcionalmente incluindo uma versão, por exemplo, https://myvault.vault.azure.net/secrets/mysecret/ ou https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931

    Por exemplo, uma referência completa seria semelhante ao seguinte:

    {@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}

    Uma URL de ponto de extremidade upstream para a Função do Azure teria a seguinte aparência:

    https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}

Observação

A cada 30 minutos, ou sempre que as configurações de ponto de extremidade upstream ou identidade gerenciada forem alteradas, o serviço relê o conteúdo secreto. Você pode acionar imediatamente uma atualização alterando as configurações de ponto de extremidade upstream.

Configurações de regra

Você pode definir regras de hub, regras de categoria e regras de evento separadamente. A regra de correspondência suporta três formatos:

  • Use um asterisco (*) para corresponder a qualquer evento.
  • Use uma vírgula (,) para unir vários eventos. Por exemplo, connected, disconnected corresponde aos eventos conectados e desconectados.
  • Use o nome do evento completo para corresponder ao evento. Por exemplo, connected corresponde ao evento conectado.

Observação

Se você estiver usando o Azure Functions com o gatilho do SignalR, o gatilho do SignalR exporá um único ponto de extremidade no seguinte formato: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>. Basta definir as configurações de modelo de URL para essa URL e manter o padrão de Configurações de regra. Consulte Integração do Serviço do SignalR para obter detalhes sobre como localizar <Function_App_URL> e <API_KEY>.

Configurações de autenticação

Você pode configurar a autenticação para cada configuração de ponto de extremidade upstream separadamente. Ao configurar a autenticação, um token é definido no cabeçalho Authentication da mensagem de upstream. Atualmente, o Serviço do Azure SignalR dá suporte aos seguintes tipos de autenticação:

  • None
  • ManagedIdentity

Ao selecionar ManagedIdentity, você deve primeiro habilitar uma identidade gerenciada no Serviço SignalR do Azure e, opcionalmente, especificar um recurso. Consulte Identidades gerenciadas para o Serviço do Azure SignalR para obter detalhes.

Definir configurações de ponto de extremidade upstream por meio do portal do Azure

Observação

Atualmente, não há suporte para a integração com o Ambiente do Serviço de Aplicativo.

  1. Acesse o Serviço do Azure SignalR.
  2. Selecione Configurações.
  3. Alterne o modo de serviço para Serverless.
  4. Adicione URLs em Padrão de URL upstream. Screenshot of AzureSignalR Service Upstream settings.
  5. Selecione Regras de Hub para abrir Configurações Upstream. Screenshot of Azure SignalR Upstream setting details.
  6. Altere Regras de Hub, Regras de Evento e Regras de Categoria inserindo o valor da regra no campo correspondente.
  7. Em Autenticação Upstream , selecione
  8. Use a identidade gerenciada. (Verifique se você habilitou a identidade gerenciada)
  9. Escolha as opções em Audiência no token emitido. Consulte Identidades gerenciadas para o Serviço do Azure SignalR para obter detalhes.

Definir configurações de ponto de extremidade upstream por meio do modelo do Gerenciador de Recursos

Para definir configurações de ponto de extremidade upstream usando um modelo do Gerenciador de Recursos do Azure, defina a propertiesupstream propriedade na propriedade. O trecho a seguir mostra como definir a upstream propriedade para criar e atualizar configurações de ponto de extremidade upstream.

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

Protocolos sem servidor

O Serviço do Azure SignalR envia mensagens para pontos de extremidade que seguem os protocolos a seguir. É possível usar a associação de gatilho do Serviço do SignalR com o aplicativo de funções, que processa esses protocolos para você.

Method

POSTAR

Cabeçalho da solicitação

Nome Descrição
X-ASRS-Connection-Id ID de conexão para a conexão do cliente.
X-ASRS-Hub Hub ao qual a conexão do cliente pertence.
X-ASRS-Category Categoria à qual a mensagem pertence.
X-ASRS-Event Evento ao qual a mensagem pertence.
X-ASRS-Signature HMAC (código de autenticação de mensagem baseada em hash) usado para validação. Consulte Assinatura para obter detalhes.
X-ASRS-User-Claims Grupo de declarações da conexão do cliente.
X-ASRS-User-Id Identidade de usuário do cliente que envia a mensagem.
X-ASRS-Client-Query A consulta da solicitação quando os clientes se conectam ao serviço.
Autenticação Token opcional quando ManagedIdentity estiver sendo usado.

Corpo da solicitação

Conectado

Tipo de conteúdo: application/json

Desconectado

Tipo de conteúdo: application/json

Nome Digitar Descrição
Erro string Mensagem de erro de uma conexão fechada. Vazio quando as conexões fecham sem erros.

Mensagem de invocação

Tipo de conteúdo: application/json ou application/x-msgpack

Nome Digitar Descrição
InvocationId string Cadeia opcional de caracteres que representa uma mensagem de invocação. Encontre detalhes em Invocações.
Destino string O mesmo que o evento e o mesmo que o destino em uma mensagem de invocação.
Argumentos Matriz de objetos Matriz que contém argumentos a serem aplicados ao método referido em Target.

Assinatura

O serviço irá calcular o código SHA256 para o valor X-ASRS-Connection-Id usando a chave de acesso primária e a chave de acesso secundária como a chave HMAC. O serviço irá defini-lo no X-ASRS-Signature cabeçalho ao fazer solicitações HTTP para um ponto de extremidade upstream:

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

Próximas etapas