Puntos de conexión ascendentes

  • Artículo

La característica de puntos de conexión ascendentes permite a Azure SignalR Service enviar mensajes y eventos de conexión a un conjunto de puntos de conexión en modo sin servidor. Puede usar puntos de conexión ascendentes para invocar un método concentrador desde clientes en modo sin servidor para notificar a los puntos de conexión cuando las conexiones de cliente están conectadas o desconectadas.

Nota:

Los puntos de conexión ascendentes solo se pueden configurar en modo sin servidor.

Configuración del punto de conexión ascendente

La configuración de un punto de conexión ascendente consta de una lista de elementos que distinguen el orden:

  • Una plantilla de dirección URL, que especifica a dónde se envían los mensajes.
  • Un conjunto de reglas.
  • Configuraciones de autenticación.

Cuando se desencadena un evento, las reglas de un elemento se comprueban una por una en orden. Los mensajes se enviarán a la primera dirección URL del punto de conexión ascendente del elemento coincidente.

Configuración de plantillas de dirección URL

Puede parametrizar la dirección URL del punto de conexión ascendente para admitir varios patrones. Hay tres parámetros predefinidos:

Parámetro predefinido Descripción
{centro} Un centro es un concepto de Azure SignalR Service. Un centro es una unidad de aislamiento. El ámbito de los usuarios y de la entrega de mensajes está restringido a un centro.
{categoría} Una categoría puede ser uno de los siguientes valores:
  • connections: eventos de duración de Conectar ion. Se activa cuando una conexión de cliente se conecta o desconecta. Incluye eventos conectados y desconectados.
  • mensajes: se desencadena cuando los clientes invocan un método de concentrador. Incluye todos los demás eventos, excepto los eventos de la categoría de conexiones .
{evento} En la categoría messages, un evento es el destino en el mensaje de invocación que envían los clientes. En la categoría connections, solo se usan connected y disconnected.

Estos parámetros predefinidos se pueden usar en el patrón de dirección URL. Los parámetros se reemplazarán por un valor especificado al evaluar la dirección URL del punto de conexión ascendente. Por ejemplo:

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

Cuando se conecte una conexión de cliente en el centro "chat", se enviará un mensaje a esta dirección URL:

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

Cuando un cliente del centro "chat" invoque el método de centro de conectividad broadcast, se enviará un mensaje a esta dirección URL:

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

Referencia de secreto de Key Vault en la configuración de la plantilla de dirección URL

La dirección URL del punto de conexión ascendente no está cifrada. Puede proteger los puntos de conexión ascendentes confidenciales mediante Key Vault y acceder a ellos con una identidad administrada.

Para habilitar la identidad administrada en la instancia de SignalR Service y concederle acceso a Key Vault:

  1. Agregue una identidad asignada por el sistema o una asignada por el usuario. Consulte Incorporación de identidades administradas en Azure Portal.

  2. Conceda el permiso de lectura de secreto para la identidad administrada en las directivas de acceso de Key Vault. Consulte Asignación de una directiva de acceso de Key Vault mediante Azure Portal

  3. Reemplace el texto confidencial por la sintaxis siguiente en el patrón de dirección URL del punto de conexión ascendente:

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

    <secret-identity> es el URI completo del plano de datos de un secreto en Key Vault y, opcionalmente, puede incluir una versión; por ejemplo, https://myvault.vault.azure.net/secrets/mysecret/ o https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931.

    Por ejemplo, una referencia completa se parecería a la siguiente:

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

    Una dirección URL del punto de conexión ascendente a La función de Azure tendría el siguiente aspecto:

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

Nota:

Cada 30 minutos, o cada vez que cambie la configuración del punto de conexión ascendente o la identidad administrada, el servicio vuelve a leer el contenido del secreto. Puede desencadenar inmediatamente una actualización cambiando la configuración del punto de conexión ascendente.

Configuración de reglas

Puede establecer reglas de concentrador, reglas de categoría y reglas de eventos por separado. La regla de coincidencia admite tres formatos:

  • Use un asterisco (*) para que coincida con cualquier evento.
  • Use una coma (,) para combinar varios eventos. Por ejemplo, connected, disconnected asocia los eventos conectados y desconectados.
  • Use el nombre de evento completo para que se asocie con el evento. Por ejemplo, connected asocia el evento conectado.

Nota:

Si usa Azure Functions con el desencadenador SignalR, el desencadenador de SignalR expondrá un único punto de conexión con el formato siguiente: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>. Solo puede establecer la configuración de la plantilla de dirección URL en esta dirección URL y mantener la Configuración de la regla como opción predeterminada. Consulte Integración de SignalR Service para obtener más información sobre cómo buscar <Function_App_URL> y <API_KEY>.

Configuración de autenticación

Puede configurar la autenticación para cada configuración de punto de conexión ascendente por separado. Al configurar la autenticación, se establece un token en el encabezado Authentication del mensaje ascendente. Actualmente, Azure SignalR Service admite los siguientes tipos de autenticación:

  • None
  • ManagedIdentity

Al seleccionar ManagedIdentity, primero debe habilitar una identidad administrada en Azure SignalR Service y, opcionalmente, especificar un recurso. Para obtener más información, consulte Identidades administradas para Azure SignalR Service.

Configuración del punto de conexión ascendente mediante Azure Portal

Nota:

La integración con App Service Environment no se admite actualmente.

  1. Vaya a Azure SignalR Service.
  2. Haga clic en Configuración.
  3. Cambie el modo de servicio a Sin servidor.
  4. Agregue las direcciones URL en Upstream URL Pattern (Patrón de dirección URL ascendente). Screenshot of AzureSignalR Service Upstream settings.
  5. Seleccione Reglas del concentrador para abrir la Configuración ascendente. Screenshot of Azure SignalR Upstream setting details.
  6. Para cambiar las reglas del centro de conectividad, las reglas de eventos y las reglas de categoría, escriba el valor de regla en el campo correspondiente.
  7. En Autenticación ascendente, seleccione
  8. Use identidad administrada. (Asegúrese de que ha habilitado la identidad administrada)
  9. Elija las opciones en Audiencia en el token emitido. Para obtener más información, consulte Identidades administradas para Azure SignalR Service.

Configuración del punto de conexión ascendente mediante la plantilla de Resource Manager

Para configurar la configuración del punto de conexión ascendente mediante una plantilla de Azure Resource Manager, establezca la upstream propiedad en la properties propiedad . En el fragmento de código siguiente se muestra cómo establecer la propiedad para crear y actualizar la upstream configuración del punto de conexión ascendente.

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

Protocolos sin servidor

Azure SignalR Service envía mensajes a los puntos de conexión que cumplen con los protocolos siguientes. Puede usar el enlace del desencadenador de SignalR Service con la aplicación de funciones, que controla estos protocolos.

Método

PUBLICAR

Encabezado de solicitud

Nombre Descripción
X-ASRS-Connection-Id Identificador de conexión para la conexión del cliente.
X-ASRS-Hub El centro al que pertenece la conexión del cliente.
X-ASRS-Category Categoría a la que pertenece el mensaje.
X-ASRS-Event Evento al que pertenece el mensaje.
X-ASRS-Signature Código de autenticación de mensajes basado en hash (HMAC) que se utiliza para la validación. Consulte Firma para obtener más información.
X-ASRS-User-Claims Un grupo de notificaciones de la conexión del cliente.
X-ASRS-User-Id Identidad de usuario del cliente que envía el mensaje.
X-ASRS-Client-Query La consulta de la solicitud cuando los clientes se conectan al servicio.
Autenticación Un token opcional cuando se usa ManagedIdentity.

Cuerpo de la solicitud

Conectado

Content-Type: application/json

Desconectado

Content-Type: application/json

Nombre Tipo Descripción
Error cadena Mensaje de error de una conexión cerrada. Está vacío cuando las conexiones se cierran sin errores.

Mensaje de invocación

Content-Type: application/json o application/x-msgpack

Nombre Tipo Descripción
InvocationId cadena Una cadena opcional que representa un mensaje de invocación. Obtenga más detalles en Invocaciones.
Destino cadena El mismo que el evento y el mismo que el destino en un mensaje de invocación.
Argumentos Matriz de objetos Una matriz que contiene los argumentos que se van a aplicar al método al que se hace referencia en Target.

Firma

El servicio calculará el código SHA256 para el valor X-ASRS-Connection-Id mediante la clave de acceso principal y la clave de acceso secundaria como clave HMAC. El servicio lo establecerá en el X-ASRS-Signature encabezado al realizar solicitudes HTTP a un punto de conexión ascendente:

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

Pasos siguientes