Enlace de salida de Notification Hubs para Azure FunctionsNotification Hubs output binding for Azure Functions

En este artículo se explica cómo enviar notificaciones Configurar las notificaciones de inserción mediante el uso de enlaces de Azure Notification Hubs en Azure Functions.This article explains how to send push notifications by using Azure Notification Hubs bindings in Azure Functions. Azure Functions admite los enlaces de salida para Notification Hubs.Azure Functions supports output bindings for Notification Hubs.

Azure Notification Hubs debe estar configurado para el servicio de notificaciones de plataforma (PNS) que desea usar.Azure Notification Hubs must be configured for the Platform Notifications Service (PNS) you want to use. Para información sobre cómo obtener notificaciones de inserción en la aplicación cliente desde Notification Hubs, consulte Introducción a Notification Hubs y seleccione la plataforma cliente de destino en la lista desplegable que aparece cerca de la parte superior de la página.To learn how to get push notifications in your client app from Notification Hubs, see Getting started with Notification Hubs and select your target client platform from the drop-down list near the top of the page.

Esta es la información de referencia para desarrolladores de Azure Functions.This is reference information for Azure Functions developers. Si está familiarizado con Azure Functions, comience con los siguientes recursos:If you're new to Azure Functions, start with the following resources:

Importante

Google ha en desuso de Google Cloud Messaging (GCM) en favor de Firebase Cloud Messaging (FCM).Google has deprecated Google Cloud Messaging (GCM) in favor of Firebase Cloud Messaging (FCM). Este enlace de salida no es compatible con FCM.This output binding doesn't support FCM. Para enviar notificaciones con FCM, use el Firebase API directamente en su función o use notificaciones de plantilla.To send notifications using FCM, use the Firebase API directly in your function or use template notifications.

Paquetes: Functions 1.xPackages - Functions 1.x

Los enlaces de Notification Hubs se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.NotificationHubs, versión 1.x.The Notification Hubs bindings are provided in the Microsoft.Azure.WebJobs.Extensions.NotificationHubs NuGet package, version 1.x. El código fuente del paquete está en el repositorio azure-webjobs-sdk-extensions de GitHub.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

En la siguiente tabla se explica cómo agregar compatibilidad para este enlace en cada entorno de desarrollo.The following table tells how to add support for this binding in each development environment.

Entorno de desarrolloDevelopment environment Para agregar compatibilidad enTo add support in
Functions 1.xFunctions 1.x
Desarrollo local: biblioteca de clases C#Local development - C# class library Instalación del paqueteInstall the package
Desarrollo local: script de C#, JavaScript, F#Local development - C# script, JavaScript, F# AutomáticoAutomatic
Desarrollo con PortalPortal development AutomáticoAutomatic

Paquetes: Functions 2.xPackages - Functions 2.x

Este enlace no está disponible en Functions 2.x.This binding is not available in Functions 2.x.

Ejemplo: plantillaExample - template

Las notificaciones que envía pueden ser notificaciones nativas o de plantilla.The notifications you send can be native notifications or template notifications. Las notificaciones nativas se envían a una plataforma cliente específica, tal como está configurado en la propiedad platform del enlace de salida.Native notifications target a specific client platform as configured in the platform property of the output binding. Las notificaciones de plantillas pueden enviarse varias plataformas.A template notification can be used to target multiple platforms.

Vea el ejemplo específico del lenguaje:See the language-specific example:

Ejemplo de plantilla de script de C#: parámetro de salidaC# script template example - out parameter

En este ejemplo, se envía una notificación a un registro de plantillas que contiene un marcador de posición message en la plantilla.This example sends a notification for a template registration that contains a message placeholder in the template.

using System;
using System.Threading.Tasks;
using System.Collections.Generic;

public static void Run(string myQueueItem,  out IDictionary<string, string> notification, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");
    notification = GetTemplateProperties(myQueueItem);
}

private static IDictionary<string, string> GetTemplateProperties(string message)
{
    Dictionary<string, string> templateProperties = new Dictionary<string, string>();
    templateProperties["message"] = message;
    return templateProperties;
}

Ejemplo de plantilla de script de C#: asincrónicoC# script template example - asynchronous

Si va a utilizar código asincrónico, no se admiten parámetros de salida.If you are using asynchronous code, out parameters are not allowed. En este caso, utilice IAsyncCollector para devolver la notificación de plantillas.In this case use IAsyncCollector to return your template notification. El código siguiente es un ejemplo asincrónico del anterior.The following code is an asynchronous example of the code above.

using System;
using System.Threading.Tasks;
using System.Collections.Generic;

public static async Task Run(string myQueueItem, IAsyncCollector<IDictionary<string,string>> notification, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");

    log.Info($"Sending Template Notification to Notification Hub");
    await notification.AddAsync(GetTemplateProperties(myQueueItem));    
}

private static IDictionary<string, string> GetTemplateProperties(string message)
{
    Dictionary<string, string> templateProperties = new Dictionary<string, string>();
    templateProperties["user"] = "A new user wants to be added : " + message;
    return templateProperties;
}

Ejemplo de plantilla de script de C#: JSONC# script template example - JSON

En este ejemplo, se envía una notificación a un registro de plantillas que contiene un marcador de posición message en la plantilla mediante una cadena JSON válida.This example sends a notification for a template registration that contains a message placeholder in the template using a valid JSON string.

using System;

public static void Run(string myQueueItem,  out string notification, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");
    notification = "{\"message\":\"Hello from C#. Processed a queue item!\"}";
}

Ejemplo de plantilla de script de C#: tipos de bibliotecaC# script template example - library types

En este ejemplo, se muestra cómo utilizar los tipos definidos en la biblioteca de Microsoft Azure Notification Hubs.This example shows how to use types defined in the Microsoft Azure Notification Hubs Library.

#r "Microsoft.Azure.NotificationHubs"

using System;
using System.Threading.Tasks;
using Microsoft.Azure.NotificationHubs;

public static void Run(string myQueueItem,  out Notification notification, TraceWriter log)
{
   log.Info($"C# Queue trigger function processed: {myQueueItem}");
   notification = GetTemplateNotification(myQueueItem);
}

private static TemplateNotification GetTemplateNotification(string message)
{
    Dictionary<string, string> templateProperties = new Dictionary<string, string>();
    templateProperties["message"] = message;
    return new TemplateNotification(templateProperties);
}

Ejemplo de plantilla de F#F# template example

En este ejemplo, se envía una notificación a un registro de plantillasmessage que contiene y location.This example sends a notification for a template registration that contains location and message.

let Run(myTimer: TimerInfo, notification: byref<IDictionary<string, string>>) =
    notification = dict [("location", "Redmond"); ("message", "Hello from F#!")]

Ejemplo de plantilla de JavaScriptJavaScript template example

En este ejemplo, se envía una notificación a un registro de plantillasmessage que contiene y location.This example sends a notification for a template registration that contains location and message.

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.IsPastDue)
    {
        context.log('Node.js is running late!');
    }
    context.log('Node.js timer trigger function ran!', timeStamp);  
    context.bindings.notification = {
        location: "Redmond",
        message: "Hello from Node!"
    };
    context.done();
};

Ejemplo: nativo de APNSExample - APNS native

En este ejemplo de script de C# se muestra cómo enviar una notificación APNS nativa.This C# script example shows how to send a native APNS notification.

#r "Microsoft.Azure.NotificationHubs"
#r "Newtonsoft.Json"

using System;
using Microsoft.Azure.NotificationHubs;
using Newtonsoft.Json;

public static async Task Run(string myQueueItem, IAsyncCollector<Notification> notification, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");

    // In this example the queue item is a new user to be processed in the form of a JSON string with 
    // a "name" value.
    //
    // The JSON format for a native APNS notification is ...
    // { "aps": { "alert": "notification message" }}  

    log.LogInformation($"Sending APNS notification of a new user");    
    dynamic user = JsonConvert.DeserializeObject(myQueueItem);    
    string apnsNotificationPayload = "{\"aps\": {\"alert\": \"A new user wants to be added (" + 
                                        user.name + ")\" }}";
    log.LogInformation($"{apnsNotificationPayload}");
    await notification.AddAsync(new AppleNotification(apnsNotificationPayload));        
}

Ejemplo: nativo de WNSExample - WNS native

En este ejemplo de script de C# se muestra cómo usar los tipos definidos en la biblioteca de Microsoft Azure Notification Hubs para enviar una notificación de WNS nativa.This C# script example shows how to use types defined in the Microsoft Azure Notification Hubs Library to send a native WNS toast notification.

#r "Microsoft.Azure.NotificationHubs"
#r "Newtonsoft.Json"

using System;
using Microsoft.Azure.NotificationHubs;
using Newtonsoft.Json;

public static async Task Run(string myQueueItem, IAsyncCollector<Notification> notification, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");

    // In this example the queue item is a new user to be processed in the form of a JSON string with 
    // a "name" value.
    //
    // The XML format for a native WNS toast notification is ...
    // <?xml version="1.0" encoding="utf-8"?>
    // <toast>
    //      <visual>
    //     <binding template="ToastText01">
    //       <text id="1">notification message</text>
    //     </binding>
    //   </visual>
    // </toast>

    log.Info($"Sending WNS toast notification of a new user");    
    dynamic user = JsonConvert.DeserializeObject(myQueueItem);    
    string wnsNotificationPayload = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
                                    "<toast><visual><binding template=\"ToastText01\">" +
                                        "<text id=\"1\">" + 
                                            "A new user wants to be added (" + user.name + ")" + 
                                        "</text>" +
                                    "</binding></visual></toast>";

    log.Info($"{wnsNotificationPayload}");
    await notification.AddAsync(new WindowsNotification(wnsNotificationPayload));        
}

AtributosAttributes

En las bibliotecas de clases de C#, use el atributo NotificationHub.In C# class libraries, use the NotificationHub attribute.

Los parámetros y las propiedades del constructor del atributo se describen en la sección de configuración.The attribute's constructor parameters and properties are described in the configuration section.

ConfiguraciónConfiguration

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json y el atributo NotificationHub:The following table explains the binding configuration properties that you set in the function.json file and the NotificationHub attribute:

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Debe establecerse en "notificationHub".Must be set to "notificationHub".
direccióndirection N/Dn/a Debe establecerse en "out".Must be set to "out".
namename N/Dn/a Nombre de variable usado en el código de función para el mensaje del Centro de notificaciones.Variable name used in function code for the notification hub message.
tagExpressiontagExpression TagExpressionTagExpression Las expresiones de etiqueta permiten especificar las notificaciones que se entregarán a un conjunto de dispositivos que se registraron para recibir las notificaciones que coincidan con estas expresiones.Tag expressions allow you to specify that notifications be delivered to a set of devices that have registered to receive notifications that match the tag expression. Para obtener más información, consulte Expresiones de etiqueta y enrutamiento.For more information, see Routing and tag expressions.
hubNamehubName HubNameHubName Nombre del recurso del Centro de notificaciones en Azure Portal.Name of the notification hub resource in the Azure portal.
conexiónconnection ConnectionStringSettingConnectionStringSetting El nombre de una configuración de aplicación que contiene una cadena de conexión de Notification Hubs.The name of an app setting that contains a Notification Hubs connection string. La cadena de conexión se debe establecer en el valor DefaultFullSharedAccessSignature de la instancia de Notification Hub.The connection string must be set to the DefaultFullSharedAccessSignature value for your notification hub. Consulte Configuración de la cadena de conexión más adelante en este artículo.See Connection string setup later in this article.
platformplatform PlataformaPlatform La propiedad de plataforma indica la plataforma cliente a donde se enviará la notificación.The platform property indicates the client platform your notification targets. De forma predeterminada, si se omite la propiedad de plataforma desde el enlace de salida, las notificaciones de plantilla se pueden usar para tener como destino cualquier plataforma configurada en el centro de notificaciones de Azure.By default, if the platform property is omitted from the output binding, template notifications can be used to target any platform configured on the Azure Notification Hub. Para obtener más información sobre cómo utilizar plantillas en general para enviar notificaciones multiplataforma con un Centro de notificaciones de Azure, consulte Templates (Plantillas).For more information on using templates in general to send cross platform notifications with an Azure Notification Hub, see Templates. Al establecerse, platform debe ser uno de los siguientes valores:When set, platform must be one of the following values:

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Ejemplo de archivo function.jsonfunction.json file example

A continuación, se muestra un ejemplo de un enlace de Notification Hubs en un archivo function.json.Here's an example of a Notification Hubs binding in a function.json file.

{
  "bindings": [
    {
      "type": "notificationHub",
      "direction": "out",
      "name": "notification",
      "tagExpression": "",
      "hubName": "my-notification-hub",
      "connection": "MyHubConnectionString",
      "platform": "apns"
    }
  ],
  "disabled": false
}

Configuración de la cadena de conexiónConnection string setup

Para usar un enlace de salida de una instancia de Notification Hub, debe configurar la cadena de conexión de la instancia.To use a notification hub output binding, you must configure the connection string for the hub. Puede seleccionar una instancia de Notification Hubs existente o crear una nuevo desde la pestaña Integrar de Azure Portal.You can select an existing notification hub or create a new one right from the Integrate tab in the Azure portal. También puede configurar la cadena de conexión de forma manual.You can also configure the connection string manually.

Para configurar la cadena de conexión a un Centro de notificaciones existente:To configure the connection string to an existing notification hub:

  1. Vaya al Centro de notificaciones en Azure Portal, elija Directivas de acceso y seleccione el botón Copiar situado junto a la directiva DefaultFullSharedAccessSignature.Navigate to your notification hub in the Azure portal, choose Access policies, and select the copy button next to the DefaultFullSharedAccessSignature policy. Con esto se copia la cadena de conexión de la directiva DefaultFullSharedAccessSignature en el Centro de notificaciones.This copies the connection string for the DefaultFullSharedAccessSignature policy to your notification hub. Esta cadena de conexión permite que la función envíe mensajes de notificación a la instancia de Notification Hubs.This connection string lets your function send notification messages to the hub. Copia de la cadena de conexión del Centro de notificacionesCopy the notification hub connection string
  2. Vaya a la aplicación de función en Azure Portal, elija Configuración de la aplicación, agregue una clave como MyHubConnectionString, pegue el elemento DefaultFullSharedAccessSignature copiado para la instancia de Notification Hubs como el valor y luego haga clic en Guardar.Navigate to your function app in the Azure portal, choose Application settings, add a key such as MyHubConnectionString, paste the copied DefaultFullSharedAccessSignature for your notification hub as the value, and then click Save.

El nombre de esta configuración de aplicación es lo que va en la configuración de conexión del enlace de salida en function.json o el atributo .NET.The name of this application setting is what goes in the output binding connection setting in function.json or the .NET attribute. Consulte la sección Configuración que apareció anteriormente en este artículo.See the Configuration section earlier in this article.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Excepciones y códigos de retornoExceptions and return codes

EnlaceBinding ReferenciaReference
Centro de notificacionesNotification Hub Guía de operacionesOperations Guide

Pasos siguientesNext steps