Выходная привязка Центра уведомлений для службы "Функции Azure"Notification Hubs output binding for Azure Functions

Эта статья объясняет, как отправлять push-уведомления с помощью привязок Центров уведомлений Azure в службе "Функции Azure".This article explains how to send push notifications by using Azure Notification Hubs bindings in Azure Functions. Служба "Функции Azure" поддерживает выходные привязки для Центров уведомлений.Azure Functions supports output bindings for Notification Hubs.

Центры уведомлений нужно настроить для служб уведомлений платформы (PNS), которые необходимо использовать.Azure Notification Hubs must be configured for the Platform Notifications Service (PNS) you want to use. Сведения о том, как получать push-уведомления в клиентское приложение из Центров уведомлений, см. в статье Начало работы с Центрами уведомлений для приложений универсальной платформы Windows. Вы также можете выбрать целевую клиентскую платформу из раскрывающегося списка в верхней части страницы.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.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Важно!

В Google используется устаревший Google Cloud Messaging (gcm) в пользу Firebase Cloud Messaging (FCM).Google has deprecated Google Cloud Messaging (GCM) in favor of Firebase Cloud Messaging (FCM). Эта выходная привязка не поддерживает FCM.This output binding doesn't support FCM. Чтобы отправлять уведомления с помощью FCM, используйте API Firebase непосредственно в функции или используйте уведомления шаблона.To send notifications using FCM, use the Firebase API directly in your function or use template notifications.

Пакеты – Функции 1.xPackages - Functions 1.x

Привязки Центров уведомлений доступны в пакете NuGet Microsoft.Azure.WebJobs.Extensions.NotificationHubs версии 1.х.The Notification Hubs bindings are provided in the Microsoft.Azure.WebJobs.Extensions.NotificationHubs NuGet package, version 1.x. Исходный код для пакета находится в репозитории GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Для добавления поддержки вTo add support in
Функции 1.xFunctions 1.x
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка – Скрипт C#, JavaScript, F#Local development - C# script, JavaScript, F# АвтоматическийAutomatic
Разработка на порталеPortal development АвтоматическийAutomatic

Packages — функции 2. x и более поздних версийPackages - Functions 2.x and higher

Эта привязка недоступна в функциях 2. x и более поздних версий.This binding is not available in Functions 2.x and higher.

Пример шаблонаExample - template

Можно отправлять собственные или шаблонные уведомления.The notifications you send can be native notifications or template notifications. Собственные уведомления нацелены на определенную клиентскую платформу, указанную в свойстве platform привязки для вывода.Native notifications target a specific client platform as configured in the platform property of the output binding. Шаблонное уведомление можно использовать для нескольких платформ.A template notification can be used to target multiple platforms.

Языковой пример см. в разделах:See the language-specific example:

Пример шаблона сценария C# — параметр выводаC# script template example - out parameter

В этом примере отправляется уведомление для регистрации шаблона, содержащего заполнитель message.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;
}

Пример шаблона сценария C# — асинхронныйC# script template example - asynchronous

При использовании асинхронного кода параметры вывода не допускаются.If you are using asynchronous code, out parameters are not allowed. В этом случае для возвращения шаблонного уведомления следует использовать IAsyncCollector.In this case use IAsyncCollector to return your template notification. Ниже приведен пример асинхронного кода, описанного выше.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;
}

Пример шаблона сценария C# — JSONC# script template example - JSON

В этом примере отправляется уведомление для регистрации шаблона, содержащего заполнитель message и использующего допустимую строку 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!\"}";
}

Пример шаблона сценария C# — типы библиотекC# script template example - library types

В этом примере показано, как использовать типы, определенные в библиотеке центров уведомлений 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);
}

Пример шаблона F#F# template example

В этом примере отправляется уведомление для регистрации шаблона, содержащего свойства location и 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#!")]

Пример шаблона JavaScriptJavaScript template example

В этом примере отправляется уведомление для регистрации шаблона, содержащего свойства location и 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();
};

Пример — собственный APNSExample - APNS native

В этом примере сценария C# показано, как отправлять собственные уведомления 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));        
}

Пример — собственный WNSExample - WNS native

В этом примере сценария C# показано, как использовать типы, определенные в библиотеке центров уведомлений Microsoft Azure, для отправки всплывающего уведомления WNS.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));        
}

АтрибутыAttributes

В библиотеках классов C# используйте атрибут NotificationHub.In C# class libraries, use the NotificationHub attribute.

Параметры конструктора атрибута и его свойства описаны в разделе конфигурации.The attribute's constructor parameters and properties are described in the configuration section.

НастройкаConfiguration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте NotificationHub:The following table explains the binding configuration properties that you set in the function.json file and the NotificationHub attribute:

свойство function.jsonfunction.json property Свойство атрибутаAttribute property ОписаниеDescription
typetype Н/Дn/a Нужно задать значение notificationHub.Must be set to notificationHub.
directiondirection Н/Дn/a Нужно задать значение out.Must be set to out.
namename Н/Дn/a Имя переменной, используемой в коде функции для сообщения Центра уведомлений.Variable name used in function code for the notification hub message.
tagExpressiontagExpression TagExpressionTagExpression Выражения тегов позволяют указать, что уведомления должны отправляться на устройства, зарегистрированные для получения уведомлений, соответствующих выражению тега.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. Дополнительные сведения см. в статье Маршрутизация и выражения тегов.For more information, see Routing and tag expressions.
hubNamehubName HubNameHubName Имя ресурса Центра уведомлений на портале Azure.Name of the notification hub resource in the Azure portal.
подключениеconnection ConnectionStringSettingConnectionStringSetting Имя параметра приложения, содержащего строку подключения Центров уведомлений.The name of an app setting that contains a Notification Hubs connection string. Для нее необходимо задать значение DefaultFullSharedAccessSignature для Центра уведомлений.The connection string must be set to the DefaultFullSharedAccessSignature value for your notification hub. Ознакомьтесь с разделом Настройка строки подключения далее в этой статье.See Connection string setup later in this article.
platformplatform ПлатформаPlatform Свойство platform указывает целевую клиентскую платформу для ваших уведомлений.The platform property indicates the client platform your notification targets. По умолчанию, если свойство платформы отсутствует в выходной привязке, шаблонные уведомления могут использоваться для любой платформы, настроенной в концентраторе уведомлений 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. Дополнительные общие сведения об использовании шаблонов для отправки кроссплатформенных уведомлений с помощью центра уведомлений Azure см. в разделе Шаблоны.For more information on using templates in general to send cross platform notifications with an Azure Notification Hub, see Templates. Если свойство platform задано, оно должно иметь одно из следующих значений:When set, platform must be one of the following values:

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Пример файла function.jsonfunction.json file example

Ниже приведен пример привязки Центров уведомлений в файле 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
}

Настройка строки подключенияConnection string setup

Для использования привязки для вывода Центра уведомлений необходимо настроить отдельную строку подключения.To use a notification hub output binding, you must configure the connection string for the hub. На портале Azure вы можете выбрать имеющийся Центр уведомлений или создать новый на вкладке Интегрировать.You can select an existing notification hub or create a new one right from the Integrate tab in the Azure portal. Кроме того, строку подключения можно настроить вручную.You can also configure the connection string manually.

Настройка строки подключения к имеющемуся Центру уведомленийTo configure the connection string to an existing notification hub:

  1. Перейдите к Центру уведомлений на портале Azure. Выберите Политики доступа, а затем нажмите кнопку копирования рядом с политикой DefaultFullSharedAccessSignature.Navigate to your notification hub in the Azure portal, choose Access policies, and select the copy button next to the DefaultFullSharedAccessSignature policy. Это позволит скопировать строку подключения политики DefaultFullSharedAccessSignature к вашему Центру уведомлений.This copies the connection string for the DefaultFullSharedAccessSignature policy to your notification hub. Эта строка подключения позволяет функции отправлять сообщения центру уведомлений.This connection string lets your function send notification messages to the hub. Копирование строки подключения к Центру уведомленийCopy the notification hub connection string
  2. Перейдите к приложению-функции на портале Azure. Выберите Параметры приложения, добавьте ключ, например MyHubConnectionString, вставьте скопированную строку подключения политики DefaultFullSharedAccessSignature к Центру уведомлений как значение, а затем нажмите кнопку Сохранить.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.

Имя параметра приложения такое же, как и параметра подключения выходной привязки в файле function.json или атрибуте .NET.The name of this application setting is what goes in the output binding connection setting in function.json or the .NET attribute. Ознакомьтесь с разделом конфигурации в этой статье.See the Configuration section earlier in this article.

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Исключения и коды возвратаExceptions and return codes

ПривязкаBinding Справочные материалыReference
Концентратор уведомленийNotification Hub Руководство по операциямOperations Guide

Дальнейшие действияNext steps