Associação de saída dos Hubs de Notificação para Azure FunctionsNotification Hubs output binding for Azure Functions

Este artigo explica como enviar notificações por push usando associações de Hubs de Notificação do Azure no Azure Functions.This article explains how to send push notifications by using Azure Notification Hubs bindings in Azure Functions. O Azure Functions oferece suporte a uma associação de saída para os Hubs de Notificação.Azure Functions supports output bindings for Notification Hubs.

Os Hubs de Notificação do Azure devem ser configurados para os PNS (Serviços de Notificações de Plataforma) que você deseja usar.Azure Notification Hubs must be configured for the Platform Notifications Service (PNS) you want to use. Para saber como obter notificações por push em seu aplicativo cliente desde Hubs de Notificação, veja Introdução aos Hubs de Notificação e selecione a plataforma de cliente de destino na lista suspensa na parte superior da 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.

Essas são as informações de referência para desenvolvedores do Azure Functions.This is reference information for Azure Functions developers. Se for novo no Azure Functions, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Importante

O Google preteriu Google Cloud Messaging (GCM) em favor do firebase Cloud Messaging (FCM).Google has deprecated Google Cloud Messaging (GCM) in favor of Firebase Cloud Messaging (FCM). Esta associação de saída não dá suporte a FCM.This output binding doesn't support FCM. Para enviar notificações usando o FCM, use a API do firebase diretamente em sua função ou use notificações de modelo.To send notifications using FCM, use the Firebase API directly in your function or use template notifications.

Pacotes - Functions 1. xPackages - Functions 1.x

As associações de Hubs de notificação são fornecidas no Microsoft.Azure.WebJobs.Extensions.NotificationHubs pacote NuGet, versão 1. x.The Notification Hubs bindings are provided in the Microsoft.Azure.WebJobs.Extensions.NotificationHubs NuGet package, version 1.x. O código-fonte do pacote está no repositório GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporte emTo add support in
Funções 1.xFunctions 1.x
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - Script do C#, JavaScript, F#Local development - C# script, JavaScript, F# AutomáticoAutomatic
Desenvolvimento de portalPortal development AutomáticoAutomatic

Pacotes - Functions 2. xPackages - Functions 2.x

Essa associação não está disponível em funções 2. x.This binding is not available in Functions 2.x.

Exemplo - modeloExample - template

As notificações enviadas podem ser notificações nativas ou notificações de modelo.The notifications you send can be native notifications or template notifications. As notificações nativas são destinadas a uma plataforma específica de cliente, conforme configurado na propriedade platform da associação de saída.Native notifications target a specific client platform as configured in the platform property of the output binding. Uma notificação de modelo pode ser usada para ter como destino várias plataformas.A template notification can be used to target multiple platforms.

Consulte o exemplo específico a um idioma:See the language-specific example:

Exemplo de modelo de script do C# - parâmetro outC# script template example - out parameter

Este exemplo envia uma notificação para um registro de modelo que contém um espaço reservado message no modelo.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;
}

Exemplo de modelo de script do C# - assíncronoC# script template example - asynchronous

Se você estiver usando o código assíncrono, os parâmetros de saída não serão permitidos.If you are using asynchronous code, out parameters are not allowed. Nesse caso, use IAsyncCollector para retornar a notificação de modelo.In this case use IAsyncCollector to return your template notification. O código a seguir é um exemplo de código assíncrono acima.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;
}

Exemplo de modelo de script do C# - JSONC# script template example - JSON

Este exemplo envia uma notificação para um registro de modelo que contém um espaço reservado message no modelo usando uma cadeia de caracteres JSON.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!\"}";
}

Exemplo de modelo script do C# - tipos de bibliotecaC# script template example - library types

Este exemplo mostra como usar tipos definidos na Biblioteca de Hubs de Notificações do Microsoft Azure.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);
}

Exemplo de modelo F#F# template example

Este exemplo envia uma notificação para um registro de modelo que contém location e message.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#!")]

Exemplo de modelo JavaScriptJavaScript template example

Este exemplo envia uma notificação para um registro de modelo que contém location e message.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();
};

Exemplo - APNS nativoExample - APNS native

Este exemplo de script C# mostra como enviar uma notificação nativa do APNS.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));        
}

Exemplo - WNS nativoExample - WNS native

Este exemplo de script C# mostra como usar tipos definidos na Biblioteca de Hubs de Notificação do Microsoft Azure para enviar uma notificação nativa WNS do sistema.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

Em bibliotecas de classes de C#, utilize o atributo NotificationHub.In C# class libraries, use the NotificationHub attribute.

Os parâmetros e as propriedades do construtor do atributo são descritos na seção Configuração.The attribute's constructor parameters and properties are described in the configuration section.

ConfiguraçãoConfiguration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no atributo NotificationHub:The following table explains the binding configuration properties that you set in the function.json file and the NotificationHub attribute:

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DESCRIÇÃODescription
tipotype n/dn/a Deve ser definido como notificationHub.Must be set to notificationHub.
directiondirection n/dn/a Deve ser definido como out.Must be set to out.
namename n/dn/a Nome da variável usada no código de função para a mensagem do hub de notificação.Variable name used in function code for the notification hub message.
tagExpressiontagExpression TagExpressionTagExpression As expressões de marca permitem que você especifique que as notificações sejam entregues a um conjunto de dispositivos registrados para receber notificações que correspondem à expressão de marca.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 saber mais, veja Expressões de marca e de roteamento.For more information, see Routing and tag expressions.
hubNamehubName HubNameHubName Nome do recurso de hub de notificação no portal do Azure.Name of the notification hub resource in the Azure portal.
conexãoconnection ConnectionStringSettingConnectionStringSetting O nome de uma configuração de aplicativo que contém uma cadeia de conexão de Hubs de Notificação.The name of an app setting that contains a Notification Hubs connection string. A cadeia de caracteres de conexão deve ser definida como o valor DefaultFullSharedAccessSignature para o hub de notificação.The connection string must be set to the DefaultFullSharedAccessSignature value for your notification hub. Veja Configuração da cadeia de conexão posteriormente neste artigo.See Connection string setup later in this article.
platformplatform PlataformaPlatform A propriedade platform indica a plataforma de cliente à qual sua notificação se destina.The platform property indicates the client platform your notification targets. Por padrão, se a propriedade da plataforma é omitida da associação de saída, as notificações de modelo podem ser usadas para atingir qualquer plataforma configurada no Hub de Notificação do 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 obter mais informações sobre como usar modelos em geral para enviar várias notificações de plataforma com um Hub de Notificação do Azure, consulte Modelos.For more information on using templates in general to send cross platform notifications with an Azure Notification Hub, see Templates. Quando definida, platform deve ser um dos seguintes valores:When set, platform must be one of the following values:

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Exemplo de arquivo function.jsonfunction.json file example

Aqui está um exemplo de uma associação de Hubs de Notificação em um arquivo 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
}

Configuração de cadeia de conexãoConnection string setup

Para usar uma associação de saída de um hub de notificação, você deve configurar a cadeia de conexão para o hub.To use a notification hub output binding, you must configure the connection string for the hub. Você pode selecionar um hub de notificação existente ou criar um novo diretamente na guia Integrar no portal do Azure.You can select an existing notification hub or create a new one right from the Integrate tab in the Azure portal. Você também pode configurar a cadeia de conexão manualmente.You can also configure the connection string manually.

Para configurar a cadeia de conexão em um hub de notificação existente:To configure the connection string to an existing notification hub:

  1. Navegue até seu hub de notificação no portal do Azure, escolha Políticas de acesso e selecione o botão Copiar ao lado da política DefaultFullSharedAccessSignature.Navigate to your notification hub in the Azure portal, choose Access policies, and select the copy button next to the DefaultFullSharedAccessSignature policy. Isso copia a cadeia de conexão para a política DefaultFullSharedAccessSignature ao hub de notificação.This copies the connection string for the DefaultFullSharedAccessSignature policy to your notification hub. Essa cadeia de conexão permite que a função envie mensagens de notificação para o hub.This connection string lets your function send notification messages to the hub. Copiar a cadeia de conexão do hub de notificaçãoCopy the notification hub connection string
  2. Navegue até seu aplicativo de funções no portal do Azure, escolha Configurações do aplicativo, adicione uma chave como MyHubConnectionString, cole o DefaultFullSharedAccessSignature copiado em seu hub de notificação como o valor e, em seguida, clique em Salvar.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.

O nome dessa configuração de aplicativo é o que está na configuração de conexão de associação de saída em function.json ou mo atributo do .NET.The name of this application setting is what goes in the output binding connection setting in function.json or the .NET attribute. Veja a seção Configuração anteriormente neste artigo.See the Configuration section earlier in this article.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Exceções e códigos de retornoExceptions and return codes

AssociaçãoBinding ReferênciaReference
Hub de notificaçãoNotification Hub Log de operaçõesOperations Guide

Próximas etapasNext steps