Desarrollo y configuración de Azure Functions con Azure SignalR ServiceAzure Functions development and configuration with Azure SignalR Service

Las aplicaciones de Azure Functions pueden aprovechar los enlaces de Azure SignalR Service para agregar funcionalidades en tiempo real.Azure Functions applications can leverage the Azure SignalR Service bindings to add real-time capabilities. Las aplicaciones cliente usan los SDK de cliente disponibles en varios lenguajes para conectarse a Azure SignalR Service y recibir mensajes en tiempo real.Client applications use client SDKs available in several languages to connect to Azure SignalR Service and receive real-time messages.

En este artículo se describen los conceptos para desarrollar y configurar una aplicación de función de Azure que se integra con SignalR Service.This article describes the concepts for developing and configuring an Azure Function app that is integrated with SignalR Service.

Configuración de SignalR ServiceSignalR Service configuration

Azure SignalR Service puede configurarse de distintos modos.Azure SignalR Service can be configured in different modes. Cuando se usa con Azure Functions, el servicio debe configurarse en modo Sin servidor.When used with Azure Functions, the service must be configured in Serverless mode.

En Azure Portal, busque la página Configuración del recurso de SignalR Service.In the Azure portal, locate the Settings page of your SignalR Service resource. Establezca Modo de servicio en Sin servidor.Set the Service mode to Serverless.

Modo SignalR Service

Desarrollo de Azure FunctionsAzure Functions development

Una aplicación en tiempo real sin servidor creada con Azure Functions y Azure SignalR Service normalmente requiere dos funciones de Azure:A serverless real-time application built with Azure Functions and Azure SignalR Service typically requires two Azure Functions:

  • Una función "negotiate" que el cliente llama para obtener un token de acceso válido de SignalR Service y la dirección URL del punto de conexión de servicio.A "negotiate" function that the client calls to obtain a valid SignalR Service access token and service endpoint URL
  • Una o varias funciones que envían mensajes o que administran la pertenencia al grupo.One or more functions that send messages or manage group membership

función de negociaciónnegotiate function

Una aplicación cliente requiere un token de acceso válido para conectarse a Azure SignalR Service.A client application requires a valid access token to connect to Azure SignalR Service. Puede ser un token de acceso anónimo o autenticado para un identificador de usuario determinado.An access token can be anonymous or authenticated to a given user ID. Las aplicaciones de SignalR Service sin servidor requieren un punto de conexión HTTP denominado "negotiate" para obtener un token y otra información de conexión, como la dirección URL del punto de conexión de SignalR Service.Serverless SignalR Service applications require an HTTP endpoint named "negotiate" to obtain a token and other connection information, such as the SignalR Service endpoint URL.

Use una función de Azure desencadenada por HTTP y el enlace de entrada SignalRConnectionInfo para generar el objeto de información de conexión.Use an HTTP triggered Azure Function and the SignalRConnectionInfo input binding to generate the connection information object. La función debe tener una ruta HTTP que termina en /negotiate.The function must have an HTTP route that ends in /negotiate.

Para más información sobre cómo crear la función de negociación, consulte la SignalRConnectionInfode referencia del enlace de entradaFor more information on how to create the negotiate function, see the SignalRConnectionInfo input binding reference.

Para aprender a crear un token autenticado, consulte Uso de la autenticación de App Service.To learn about how to create an authenticated token, refer to Using App Service Authentication.

Envío de mensajes y administración de la pertenencia a gruposSending messages and managing group membership

Use el enlace de salida SignalR para enviar mensajes a los clientes conectados a Azure SignalR Service.Use the SignalR output binding to send messages to clients connected to Azure SignalR Service. Puede difundir mensajes a todos los clientes, o enviarlos a un subconjunto de clientes que están autenticados con un identificador de usuario específico o que se han agregado a un grupo determinado.You can broadcast messages to all clients, or you can send them to a subset of clients that are authenticated with a specific user ID or have been added to a specific group.

Se pueden agregar usuarios a uno o más grupos.Users can be added to one or more groups. También puede usar el enlace de salida de SignalR para agregar o quitar usuarios en los grupos.You can also use the SignalR output binding to add or remove users to/from groups.

Para más información, consulte la SignalR de referencia del enlace de salida.For more information, see the SignalR output binding reference.

Concentradores de SignalRSignalR Hubs

SignalR tiene un concepto de "concentradores".SignalR has a concept of "hubs". Cada conexión de cliente y cada mensaje enviado desde Azure Functions se limitan a un concentrador concreto.Each client connection and each message sent from Azure Functions is scoped to a specific hub. Puede usar concentradores como una manera de separar las conexiones y los mensajes en espacios de nombres lógicos.You can use hubs as a way to separate your connections and messages into logical namespaces.

Desarrollo de clienteClient development

Las aplicaciones cliente de SignalR pueden aprovechar el SDK de cliente de SignalR en uno de varios lenguajes para conectarse fácilmente a Azure SignalR Service y recibir mensajes de este.SignalR client applications can leverage the SignalR client SDK in one of several languages to easily connect to and receive messages from Azure SignalR Service.

Configuración de una conexión de clienteConfiguring a client connection

Para conectarse a SignalR Service, un cliente debe realizar una negociación de conexión correcta que consta de estos pasos:To connect to SignalR Service, a client must complete a successful connection negotiation that consists of these steps:

  1. Realice una solicitud al punto de conexión HTTP negotiate mencionado anteriormente para obtener información de conexión válidaMake a request to the negotiate HTTP endpoint discussed above to obtain valid connection information
  2. Conéctese a SignalR Service mediante la dirección URL del punto de conexión de servicio y el token de acceso obtenido del punto de conexión negotiate.Connect to SignalR Service using the service endpoint URL and access token obtained from the negotiate endpoint

Los SDK de cliente de SignalR ya contienen la lógica necesaria para realizar el enlace de negociación.SignalR client SDKs already contain the logic required to perform the negotiation handshake. Pase la dirección URL del punto de conexión de negociación, menos el segmento negotiate, al elemento HubConnectionBuilder del SDK.Pass the negotiate endpoint's URL, minus the negotiate segment, to the SDK's HubConnectionBuilder. Este es un ejemplo en JavaScript:Here is an example in JavaScript:

const connection = new signalR.HubConnectionBuilder()
  .withUrl('https://my-signalr-function-app.azurewebsites.net/api')
  .build()

Por convención, el SDK anexa automáticamente /negotiate a la dirección URL y lo usa para comenzar la negociación.By convention, the SDK automatically appends /negotiate to the URL and uses it to begin the negotiation.

Nota

Si va a usar el SDK de JavaScript/TypeScript en un explorador, deberá habilitar el uso compartido de recursos entre orígenes (CORS) en la aplicación de función.If you are using the JavaScript/TypeScript SDK in a browser, you need to enable cross-origin resource sharing (CORS) on your Function App.

Para más información sobre cómo usar el SDK de cliente de SignalR, consulte la documentación correspondiente a su lenguaje:For more information on how to use the SignalR client SDK, refer to the documentation for your language:

Envío de mensajes desde un cliente hasta el servicioSending messages from a client to the service

Aunque el SDK de SignalR permite que las aplicaciones cliente invoquen la lógica de back-end en un concentrador de SignalR, esta funcionalidad no se admite aún cuando se usa SignalR Service con Azure Functions.Although the SignalR SDK allows client applications to invoke backend logic in a SignalR hub, this functionality is not yet supported when you use SignalR Service with Azure Functions. Use solicitudes HTTP para invocar Azure Functions.Use HTTP requests to invoke Azure Functions.

Configuración de Azure FunctionsAzure Functions configuration

Las aplicaciones de Azure Functions que se integran con Azure SignalR Service se pueden implementar como cualquier aplicación de función de Azure normal, mediante técnicas como implementación continua, implementación de archivos ZIP y ejecutar desde el paquete.Azure Function apps that integrate with Azure SignalR Service can be deployed like any typical Azure Function app, using techniques such as continuously deployment, zip deployment, and run from package.

Sin embargo, hay algunas consideraciones especiales para las aplicaciones que usan los enlaces de SignalR Service.However, there are a couple of special considerations for apps that use the SignalR Service bindings. Si el cliente se ejecuta en un explorador, CORS debe estar habilitado.If the client runs in a browser, CORS must be enabled. Y si la aplicación requiere autenticación, puede integrar el punto de conexión de negociación con la autenticación de App Service.And if the app requires authentication, you can integrate the negotiate endpoint with App Service Authentication.

Habilitación de CORSEnabling CORS

El cliente de JavaScript/TypeScript realiza solicitudes HTTP a la función de negociación para iniciar la negociación de la conexión.The JavaScript/TypeScript client makes HTTP requests to the negotiate function to initiate the connection negotiation. Cuando la aplicación cliente se hospeda en un dominio diferente al de la aplicación de función de Azure, se debe habilitar el uso compartido de recursos entre orígenes (CORS) en la aplicación de función o el explorador bloqueará las solicitudes.When the client application is hosted on a different domain than the Azure Function app, cross-origin resource sharing (CORS) must be enabled on the Function app or the browser will block the requests.

LocalhostLocalhost

Cuando se ejecuta la aplicación de función en el equipo local, puede agregar una sección Host a local.settings.json para habilitar CORS.When running the Function app on your local computer, you can add a Host section to local.settings.json to enable CORS. En la sección Host, agregue dos propiedades:In the Host section, add two properties:

  • CORS: escriba la URL base que es el origen de la aplicación cliente.CORS - enter the base URL that is the origin the client application
  • CORSCredentials: establézcala en true para permitir solicitudes "withCredentials".CORSCredentials - set it to true to allow "withCredentials" requests

Ejemplo:Example:

{
  "IsEncrypted": false,
  "Values": {
    // values
  },
  "Host": {
    "CORS": "http://localhost:8080",
    "CORSCredentials": true
  }
}

Nube - CORS en Azure FunctionsCloud - Azure Functions CORS

Para habilitar CORS en una aplicación de función de Azure, vaya a la pantalla de configuración de CORS en la pestaña Características de la plataforma de la aplicación de función en Azure Portal.To enable CORS on an Azure Function app, go to the CORS configuration screen under the Platform features tab of your Function app in the Azure portal.

Nota

La configuración de CORS todavía no está disponible en el plan de Consumo para Linux de Azure Functions.CORS configuration is not yet available in Azure Functions Linux Consumption plan. Use Azure API Management para habilitar CORS.Use Azure API Management to enable CORS.

Debe estar habilitado CORS con Access-Control-Allow-Credentials para que el cliente de SignalR llame a la función de negociación.CORS with Access-Control-Allow-Credentials must be enabled for the SignalR client to call the negotiate function. Active la casilla para habilitarlo.Select the checkbox to enable it.

En la sección Orígenes permitidos, agregue una entrada con la dirección URL base de origen de la aplicación web.In the Allowed origins section, add an entry with the origin base URL of your web application.

Configuración de CORS

Nube: Azure API ManagementCloud - Azure API Management

Azure API Management proporciona una puerta de enlace de API que agrega funcionalidades a los servicios back-end existentes.Azure API Management provides an API gateway that adds capabilities to existing back-end services. Puede usarlo para agregar CORS a la aplicación de función.You can use it to add CORS to your function app. Ofrece un nivel de consumo con precios de pago por acción y una concesión gratuita mensual.It offers a consumption tier with pay-per-action pricing and a monthly free grant.

Consulte la documentación de API Management para obtener información sobre cómo importar una aplicación de Azure Function.Refer to the API Management documentation for information on how to import an Azure Function app. Una vez importado, puede agregar una directiva de entrada para habilitar CORS con compatibilidad Access-Control-Allow-Credentials.Once imported, you can add an inbound policy to enable CORS with Access-Control-Allow-Credentials support.

<cors allow-credentials="true">
  <allowed-origins>
    <origin>https://azure-samples.github.io</origin>
  </allowed-origins>
  <allowed-methods>
    <method>GET</method>
    <method>POST</method>
  </allowed-methods>
  <allowed-headers>
    <header>*</header>
  </allowed-headers>
  <expose-headers>
    <header>*</header>
  </expose-headers>
</cors>

Configure los clientes SignalR para usar la dirección URL de API Management.Configure your SignalR clients to use the API Management URL.

Uso de la autenticación de App ServiceUsing App Service Authentication

Azure Functions cuenta con autenticación integrada y admite proveedores conocidos, como Facebook, Twitter, Google, Cuenta Microsoft y Azure Active Directory.Azure Functions has built-in authentication, supporting popular providers such as Facebook, Twitter, Microsoft Account, Google, and Azure Active Directory. Esta característica se puede integrar con el enlace SignalRConnectionInfo para crear conexiones a Azure SignalR Service que se han autenticado con un identificador de usuario.This feature can be integrated with the SignalRConnectionInfo binding to create connections to Azure SignalR Service that have been authenticated to a user ID. La aplicación puede enviar mensajes mediante el enlace de salida SignalR que se destinan a ese identificador de usuario.Your application can send messages using the SignalR output binding that are targeted to that user ID.

En Azure Portal, en la pestaña Características de la plataforma de la aplicación de función, abra la ventana de configuración Autenticación/autorización.In the Azure portal, in your Function app's Platform features tab, open the Authentication/authorization settings window. Siga la documentación de Autenticación de App Service para configurar la autenticación mediante un proveedor de identidades de su elección.Follow the documentation for App Service Authentication to configure authentication using an identity provider of your choice.

Una vez configurada, las solicitudes HTTP autenticadas incluirán los encabezados x-ms-client-principal-name y x-ms-client-principal-id que contienen, respectivamente, el nombre de usuario y el identificador de usuario de la identidad autenticada.Once configured, authenticated HTTP requests will include x-ms-client-principal-name and x-ms-client-principal-id headers containing the authenticated identity's username and user ID, respectively.

Puede usar estos encabezados en la configuración de enlace SignalRConnectionInfo para crear las conexiones autenticadas.You can use these headers in your SignalRConnectionInfo binding configuration to create authenticated connections. Este es un ejemplo de la función de negociación de C# que usa el encabezado x-ms-client-principal-id.Here is an example C# negotiate function that uses the x-ms-client-principal-id header.

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

A continuación, puede enviar mensajes a ese usuario si establece la propiedad UserId de un mensaje de SignalR.You can then send messages to that user by setting the UserId property of a SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will only be sent to these user IDs
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Para información sobre otros lenguajes, consulte los enlaces de Azure SignalR Service para hacer referencia a Azure Functions.For information on other languages, see the Azure SignalR Service bindings for Azure Functions reference.

Pasos siguientesNext steps

En este artículo, ha aprendido a desarrollar y configurar aplicaciones de SignalR Service sin servidor con Azure Functions.In this article, you have learned how to develop and configure serverless SignalR Service applications using Azure Functions. Intente crear una aplicación por su cuenta mediante uno de los inicios rápidos o tutoriales de la página de información general de SignalR Service.Try creating an application yourself using one of the quick starts or tutorials on the SignalR Service overview page.