Notification Hubs-Ausgabebindung für Azure Functions

Dieser Artikel erläutert das Senden von Pushbenachrichtigungen mithilfe von Azure Notification Hubs-Bindungen in Azure Functions. Azure Functions unterstützt Ausgabebindungen für Notification Hubs.

Azure Notification Hubs muss für den Plattformbenachrichtigungsdienst (PNS) konfiguriert sein, den Sie verwenden möchten. Informationen zum Empfang von Pushbenachrichtigungen von Notification Hubs in Ihrer Client-App finden Sie unter Erste Schritte mit Notification Hubs. Wählen Sie dort in der Dropdownliste oben auf der Seite die Zielplattform für den Client aus.

Dies sind Referenzinformationen für Azure Functions-Entwickler. Falls Sie mit Azure Functions noch nicht vertraut sind, beginnen Sie mit den folgenden Ressourcen:

Wichtig

Google Cloud Messaging (GCM) wurde von Google eingestellt und durch Firebase Cloud Messaging (FCM) ersetzt. Diese Ausgabebindung unterstützt FCM nicht. Verwenden Sie die Firebase-API direkt in Ihrer Funktion, oder nutzen Sie Vorlagenbenachrichtigungen, um Benachrichtigungen mithilfe von FCM zu senden.

Pakete: Functions 1.x

Die Notification Hubs-Bindungen werden im NuGet-Paket Microsoft.Azure.WebJobs.Extensions.NotificationHubs, Version 1.x bereitgestellt. Den Quellcode für das Paket finden Sie im GitHub-Repository azure-webjobs-sdk-extensions.

Der folgenden Tabelle können Sie entnehmen, wie Sie Unterstützung für diese Bindung in den einzelnen Entwicklungsumgebungen hinzufügen.

Entwicklungsumgebung Hinzufügen von Unterstützung in
Functions 1.x
Lokale Entwicklung – C#-Klassenbibliothek Installieren des Pakets
Lokale Entwicklung – C#-Skript, JavaScript, F# Automatisch
Entwicklung im Portal Automatisch

Pakete: Functions 2.x oder höher

Diese Bindung ist in Functions 2.x und höher nicht verfügbar.

Beispiel: Vorlage

Die von Ihnen gesendeten Benachrichtigungen können native Benachrichtigungen oder Vorlagenbenachrichtigungen sein. Native Benachrichtigungen sind für eine spezifische Clientplattform bestimmt. Dies wird in der platform-Eigenschaft der Ausgabebindung konfiguriert. Eine Vorlagenbenachrichtigung kann für mehrere Plattformen verwendet werden.

Sehen Sie sich das sprachspezifische Beispiel an:

C#-Skriptvorlagenbeispiel: Ausgabeparameter

In diesem Beispiel wird eine Benachrichtigung für eine Vorlagenregistrierung gesendet, bei der in der Vorlage ein message-Platzhalter enthalten ist.

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#-Skriptvorlagenbeispiel: asynchron

Wenn Sie asynchronen Code verwenden, sind out-Parameter nicht zulässig. Verwenden Sie in diesem Fall IAsyncCollector, um die Vorlagenbenachrichtigung zurückzugeben. Der folgende Code ist ein asynchrones Beispiel des obigen Codes.

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#-Skriptvorlagenbeispiel: JSON

In diesem Beispiel wird eine Benachrichtigung für eine Vorlagenregistrierung, die den Platzhalter message in der Vorlage enthält, über eine gültige JSON-Zeichenfolge gesendet.

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#-Skriptvorlagenbeispiel: Bibliothekstypen

Dieses Beispiel zeigt, wie Sie in der Bibliothek für Microsoft Azure Notification Hubs definierte Typen verwenden.

#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#-Vorlagenbeispiel

In diesem Beispiel wird eine Benachrichtigung für eine Vorlagenregistrierung gesendet, die location und message enthält.

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

JavaScript-Vorlagenbeispiel

In diesem Beispiel wird eine Benachrichtigung für eine Vorlagenregistrierung gesendet, die location und message enthält.

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();
};

Beispiel: APNS nativ

Dieses C#-Skriptbeispiel zeigt das Senden einer nativen APNS-Benachrichtigung.

#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));        
}

Beispiel: WNS nativ

In diesem C#-Skriptbeispiel wird gezeigt, wie Sie in der Microsoft Azure Notification Hubs-Bibliothek definierte Typen zum Senden einer nativen WNS-Popupbenachrichtigung verwenden.

#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

Verwenden Sie in C#-Klassenbibliotheken das Attribut NotificationHub.

Die Konstruktorparameter und Eigenschaften des Attributs werden im Abschnitt Konfiguration beschrieben.

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im NotificationHub-Attribut festlegen:

Eigenschaft von „function.json“ Attributeigenschaft BESCHREIBUNG
type Muss auf notificationHub festgelegt sein.
direction Muss auf out festgelegt sein.
name Variablenname, der im Funktionscode für die Notification Hub-Nachricht verwendet wird
tagExpression TagExpression Mit Tagausdrücken können Sie Benachrichtigungen an eine Gruppe von Geräten übermitteln, die sich für den Empfang von Benachrichtigungen, die dem Tagausdruck entsprechen, registriert haben. Weitere Informationen finden Sie unter Weiterleitung und Tagausdrücke.
hubName HubName Name der Notification Hub-Ressource im Azure-Portal
connection ConnectionStringSetting Der Name einer App-Einstellung, die eine Notification Hubs-Verbindungszeichenfolge enthält. Die Verbindungszeichenfolge muss auf den Wert DefaultFullSharedAccessSignature für Ihren Notification Hub festgelegt werden. Weitere Informationen finden Sie unter Verbindungszeichenfolgen-Setup weiter unten in diesem Artikel.
platform Plattform Mit der platform-Eigenschaft wird die Clientplattform Ihrer Benachrichtigungsziele angegeben. Wenn die Plattformeigenschaft aus der Ausgabebindung weggelassen wird, können Vorlagenbenachrichtigungen für alle Zielplattformen verwendet werden, die auf dem Azure Notification Hub konfiguriert sind. Weitere Informationen zur allgemeinen Verwendung von Vorlagen zum Senden von plattformübergreifenden Benachrichtigungen mit einem Azure Notification Hub finden Sie unter Vorlagen. Wenn platform festgelegt wird, muss einer der folgenden Werte verwendet werden:

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.

Beispiel für die Datei „function.json“

Hier sehen Sie ein Beispiel für eine Notification Hubs-Bindung in einer Datei function.json.

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

Verbindungszeichenfolgen-Setup

Um eine Notification Hubs-Ausgabebindung zu verwenden, müssen Sie die Verbindungszeichenfolge für den Hub konfigurieren. Sie können einen vorhandenen Notification Hub auswählen oder über die Registerkarte Integrieren im Azure-Portal einen neuen erstellen. Sie können die Verbindungszeichenfolge auch manuell konfigurieren.

So konfigurieren Sie die Verbindungszeichenfolge für einen vorhandenen Notification Hub:

  1. Navigieren Sie im Azure-Portal zum Notification Hub, wählen Sie Zugriffsrichtlinien, und klicken Sie auf die Kopierschaltfläche neben der Richtlinie DefaultFullSharedAccessSignature. Dadurch wird die Verbindungszeichenfolge für die Richtlinie DefaultFullSharedAccessSignature in Ihren Notification Hub kopiert. Mit dieser Verbindungszeichenfolge kann Ihre Funktion Benachrichtigungen an den Hub senden. Kopieren der Notification Hub-Verbindungszeichenfolge
  2. Navigieren Sie im Azure-Portal zu Ihrer Funktions-App, wählen Sie Anwendungseinstellungen aus, und fügen Sie einen Schlüssel (etwa MyHubConnectionString) hinzu. Fügen Sie die kopierte Richtlinie DefaultFullSharedAccessSignature für Ihren Notification Hub als Wert ein, und klicken Sie anschließend auf Speichern.

Der Name der Anwendungseinstellung wird in die Verbindungseinstellung der Ausgabebindung in function.json oder im .NET-Attribut übernommen. Weitere Informationen finden Sie im Konfigurationsabschnitt weiter oben in diesem Artikel.

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.

Ausnahmen und Rückgabecodes

Bindung Verweis
Notification Hub Betriebsleitfaden

Nächste Schritte