Registrierungsverwaltung

In diesem Artikel wird erläutert, wie Sie Geräte mit Azure Notification Hubs registrieren, um Pushbenachrichtigungen zu erhalten. Der Artikel beschreibt Registrierungen auf hoher Ebene und führt dann die beiden Hauptmuster für die Registrierung von Geräten ein: die direkte Registrierung vom Gerät zum Benachrichtigungshub und die Registrierung über ein Anwendungs-Back-End.

Was ist die Geräteregistrierung?

Die Geräteregistrierung mit einem Benachrichtigungshub erfolgt mithilfe einer Registrierung oder Installation.

Registrationen

Bei einer Registrierung wird das PNS-Handle (Platform Notification Service) für ein Gerät Tags und ggf. einer Vorlage zugeordnet. Das PNS-Handle kann ein ChannelURI oder eine Gerätetokenregistrierungs-ID sein. Tags werden verwendet, um Benachrichtigungen an den richtigen Satz von Gerätehandles weiterzuleiten. Weitere Informationen finden Sie unter Weiterleitung und Tagausdrücke. Vorlagen werden verwendet, um die Transformation pro Registrierung zu implementieren. Weitere Informationen finden Sie unter "Vorlagen".

Hinweis

Azure Notification Hubs unterstützt maximal 60 Tags pro Gerät.

Installationen

Eine Installation ist eine erweiterte Registrierung, die eine Reihe von Push-bezogenen Eigenschaften enthält. Es ist der neueste und beste Ansatz, Ihre Geräte mithilfe des serverseitigen .NET SDK (Notification Hub SDK für Back-End-Vorgänge) zu registrieren. Sie können auch den Rest-API-Ansatz von Notification Hubs verwenden, um Installationen auf dem Clientgerät selbst zu registrieren. Wenn Sie einen Back-End-Dienst verwenden, sollten Sie das Notification Hubs SDK für Back-End-Vorgänge verwenden können.

Im Folgenden sind einige wichtige Vorteile für die Verwendung von Installationen aufgeführt:

• Das Erstellen oder Aktualisieren einer Installation ist vollständig idempotent. Sie können es ohne Sorgen bezüglich doppelter Registrierungen erneut versuchen.
• Das Installationsmodell unterstützt ein spezielles Tagformat ($InstallationId:{INSTALLATION_ID}), mit dem eine Benachrichtigung direkt an das jeweilige Gerät gesendet werden kann. Wenn der App-Code beispielsweise eine Installations-ID joe93developer für dieses bestimmte Gerät festlegt, kann ein Entwickler dieses Gerät als Ziel festlegen, wenn eine Benachrichtigung an das $InstallationId:{joe93developer} Tag gesendet wird. Auf diese Weise können Sie auf ein bestimmtes Gerät abzielen, ohne zusätzliche Codierung vornehmen zu müssen.
• Durch die Verwendung von Installationen können Sie auch partielle Registrierungsupdates durchführen. Das partielle Update einer Installation wird mit einer PATCH-Methode mithilfe des JSON-Patch Standards angefordert. Diese Methode ist nützlich, wenn Sie Tags für die Registrierung aktualisieren möchten. Sie müssen die gesamte Registrierung nicht nach unten ziehen und dann alle vorherigen Tags erneut senden.

Eine Installation kann die folgenden Eigenschaften enthalten. Eine vollständige Auflistung der Installationseigenschaften finden Sie unter Erstellen oder Überschreiben einer Installation mit REST-API oder Installationseigenschaften.

// Example installation format to show some supported properties
{
    installationId: "",
    expirationTime: "",
    tags: [],
    platform: "",
    pushChannel: "",
    ………
    templates: {
        "templateName1" : {
            body: "",
            tags: [] },
        "templateName2" : {
            body: "",
            // Headers are for Windows Store only
            headers: {
                "X-WNS-Type": "wns/tile" }
            tags: [] }
    },
    secondaryTiles: {
        "tileId1": {
            pushChannel: "",
            tags: [],
            templates: {
                "otherTemplate": {
                    bodyTemplate: "",
                    headers: {
                        ... }
                    tags: [] }
            }
        }
    }
}

Hinweis

Standardmäßig laufen Registrierungen und Installationen nicht ab.

Registrierungen und Installationen müssen ein gültiges PNS-Handle für jedes Gerät/jeden Kanal enthalten. Da PNS-Handles nur in einer Client-App auf dem Gerät abgerufen werden können, besteht ein Muster darin, sich direkt auf diesem Gerät mit der Client-App zu registrieren. Zum anderen könnten Sicherheitsaspekte und Geschäftslogik, die sich auf Tags beziehen, erforderlich machen, dass Sie die Geräteregistrierung im App-Back-End verwalten.

Wenn die Pushbenachrichtigung vom PNS an ein abgelaufenes Handle übermittelt wird, bereinigt Azure Notification Hubs automatisch den zugehörigen Datensatz der Installation/Registrierung basierend auf der Antwort vom PNS-Server. Um abgelaufene Datensätze von einem sekundären Benachrichtigungshub zu bereinigen, fügen Sie benutzerdefinierte Logik hinzu, die Feedback von jedem Senden verarbeitet. Beenden Sie dann die Installation/Registrierung im sekundären Benachrichtigungshub.

Hinweis

Die Installations-APIs unterstützen den Baidu-Dienst nicht (obwohl die Registrierungs-API funktioniert).

Schablonen

Wenn Sie Vorlagen verwenden möchten, enthält die Geräteinstallation auch alle Vorlagen, die diesem Gerät zugeordnet sind, in einem JSON-Format (siehe Beispiel im vorherigen Abschnitt). Die Vorlagennamen helfen dabei, unterschiedliche Vorlagen gezielt für dasselbe Gerät anzuwenden.

Jeder Vorlagenname ist einem Vorlagentext und einer optionalen Gruppe von Tags zugeordnet. Jede Plattform kann zusätzliche Vorlageneigenschaften aufweisen. Bei APNs können Sie eine Ablaufeigenschaft auf eine Konstante oder auf einen Vorlagenausdruck festlegen. Eine vollständige Auflistung der Installationseigenschaften finden Sie unter Erstellen oder Überschreiben einer Installation mit REST-Thema .

Sekundäre Kacheln für Windows Store-Apps

Für Windows Store-Client-Anwendungen ist das Senden von Benachrichtigungen an sekundäre Kacheln identisch mit dem Senden an die primäre Kachel. Dies wird auch in Installationen unterstützt. Sekundäre Kacheln verfügen über einen unterschiedlichen ChannelUri, der vom SDK in der Client-App transparent behandelt wird.

Das SecondaryTiles-Wörterbuch verwendet dieselbe TileId, die zum Erstellen des SecondaryTiles-Objekts in Ihrer Windows Store-App verwendet wird. Wie beim primären ChannelUri können sich ChannelUris sekundärer Kacheln jederzeit ändern. Damit die Installationen im Notification Hub aktuell bleiben, müssen sie vom Gerät mit den aktuellen ChannelUris der sekundären Kacheln aktualisiert werden.

Registrierungsverwaltung vom Gerät

Beim Verwalten der Geräteregistrierung von Client-Apps ist das Back-End nur für das Senden von Benachrichtigungen verantwortlich. Client-Apps sorgen dafür, dass PNS-Handles auf dem neuesten Stand bleiben, und registrieren Tags. Die folgende Abbildung veranschaulicht dieses Muster.

Das Gerät ruft zuerst das PNS-Handle aus dem PNS ab und registriert sich dann direkt beim Benachrichtigungshub. Nachdem die Registrierung erfolgreich war, kann das Back-End der App eine Benachrichtigung für diese Registrierung senden. Weitere Informationen darüber, wie Sie Benachrichtigungen senden können, finden Sie unter Routing- und Tagausdrücke.

In diesem Fall verwenden Sie nur Lauschrechte, um über das Gerät auf die Notification Hubs zuzugreifen. Weitere Informationen finden Sie unter Sicherheit.

Die Registrierung vom Gerät ist die einfachste Methode, hat aber einige Nachteile:

• Eine Client-App kann ihre Tags nur aktualisieren, wenn die App aktiv ist. Wenn ein Benutzer beispielsweise über zwei Geräte verfügt, die Tags im Zusammenhang mit Sportteams registrieren, wenn sich das erste Gerät für ein zusätzliches Tag registriert (z. B. Seahawks), empfängt das zweite Gerät die Benachrichtigungen über die Seahawks erst, wenn die App auf dem zweiten Gerät ein zweites Mal ausgeführt wird. Im Allgemeinen ist die Verwaltung von Tags aus dem Back-End eine wünschenswerte Option, wenn Tags von mehreren Geräten betroffen sind.
• Da Apps gehackt werden können, erfordert die Sicherung der Registrierung für bestimmte Tags zusätzliche Sorgfalt, wie im Artikel Sicherheit erläutert.

Beispielcode zum Registrieren mit einem Benachrichtigungshub von einem Gerät mithilfe einer Installation

Derzeit wird dies nur mit der REST-API für Benachrichtigungshubs unterstützt.

Sie können die PATCH-Methode auch mit dem JSON-Patch Standard zum Aktualisieren der Installation verwenden.

class DeviceInstallation
{
    public string installationId { get; set; }
    public string platform { get; set; }
    public string pushChannel { get; set; }
    public string[] tags { get; set; }

    private async Task<HttpStatusCode> CreateOrUpdateInstallationAsync(DeviceInstallation deviceInstallation,
        string hubName, string listenConnectionString)
    {
        if (deviceInstallation.installationId == null)
            return HttpStatusCode.BadRequest;

        // Parse connection string
        ConnectionStringUtility connectionSaSUtil = new ConnectionStringUtility(listenConnectionString);
        string hubResource = "installations/" + deviceInstallation.installationId + "?";
        string apiVersion = "api-version=2015-04";

        // Determine the targetUri that we will sign
        string uri = connectionSaSUtil.Endpoint + hubName + "/" + hubResource + apiVersion;

        //=== Generate SaS Security Token for Authorization header ===
        string SasToken = connectionSaSUtil.getSaSToken(uri, 60);

        using (var httpClient = new HttpClient())
        {
            string json = JsonConvert.SerializeObject(deviceInstallation);

            httpClient.DefaultRequestHeaders.Add("Authorization", SasToken);

            var response = await httpClient.PutAsync(uri, new StringContent(json, System.Text.Encoding.UTF8, "application/json"));
            return response.StatusCode;
        }
    }

    var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

    string installationId = null;
    var settings = ApplicationData.Current.LocalSettings.Values;

    // If we didn't store an installation ID in application data, create and store as application data.
    if (!settings.ContainsKey("__NHInstallationId"))
    {
        installationId = Guid.NewGuid().ToString();
        settings.Add("__NHInstallationId", installationId);
    }

    installationId = (string)settings["__NHInstallationId"];

    var deviceInstallation = new DeviceInstallation
    {
        installationId = installationId,
        platform = "wns",
        pushChannel = channel.Uri,
        //tags = tags.ToArray<string>()
    };

    var statusCode = await CreateOrUpdateInstallationAsync(deviceInstallation, 
                    "<HUBNAME>", "<SHARED LISTEN CONNECTION STRING>");

    if (statusCode != HttpStatusCode.Accepted)
    {
        var dialog = new MessageDialog(statusCode.ToString(), "Registration failed. Installation Id : " + installationId);
        dialog.Commands.Add(new UICommand("OK"));
        await dialog.ShowAsync();
    }
    else
    {
        var dialog = new MessageDialog("Registration successful using installation Id : " + installationId);
        dialog.Commands.Add(new UICommand("OK"));
        await dialog.ShowAsync();
    }
}

Beispielcode zur Registrierung bei einem Notification Hub über ein Gerät mithilfe einer Registrierung

Diese Methoden erstellen oder aktualisieren eine Registrierung für das Gerät, auf dem sie aufgerufen werden. Dies bedeutet, dass Sie zum Aktualisieren des Handles oder der Tags die gesamte Registrierung überschreiben müssen. Denken Sie daran, dass Registrierungen vorübergehend sind, daher sollten Sie immer über einen zuverlässigen Speicher mit den aktuellen Tags verfügen, die ein bestimmtes Gerät benötigt.

// Initialize the notification hub
NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(listenConnString, hubName);

// The Device ID from the PNS
var pushChannel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

// If you are registering from the client itself, then store this registration ID in device
// storage. Then when the app starts, you can check if a registration ID already exists or not before
// creating.
var settings = ApplicationData.Current.LocalSettings.Values;

// If we didn't store a registration ID in application data, store in application data.
if (!settings.ContainsKey("__NHRegistrationId"))
{
    // Make sure there are no existing registrations for this push handle (used for iOS and Android)    
    string newRegistrationId = null;
    var registrations = await hub.GetRegistrationsByChannelAsync(pushChannel.Uri, 100);
    foreach (RegistrationDescription registration in registrations)
    {
        if (newRegistrationId == null)
        {
            newRegistrationId = registration.RegistrationId;
        }
        else
        {
            await hub.DeleteRegistrationAsync(registration);
        }
    }

    newRegistrationId = await hub.CreateRegistrationIdAsync();

    settings.Add("__NHRegistrationId", newRegistrationId);
}

string regId = (string)settings["__NHRegistrationId"];

RegistrationDescription registration = new WindowsRegistrationDescription(pushChannel.Uri);
registration.RegistrationId = regId;
registration.Tags = new HashSet<string>(YourTags);

try
{
    await hub.CreateOrUpdateRegistrationAsync(registration);
}
catch (Microsoft.WindowsAzure.Messaging.RegistrationGoneException e)
{
    settings.Remove("__NHRegistrationId");
}

Registrierungsverwaltung aus einem Back-End

Für die Verwaltung von Registrierungen aus dem Back-End müssen zusätzlichen Code geschrieben werden. Bei jedem Start muss die App auf dem Gerät das aktualisierte PNS-Handle (zusammen mit den Tags und Vorlagen) für das Back-End bereitstellen, und das Back-End muss dieses Handle im Notification Hub aktualisieren. Die folgende Abbildung veranschaulicht dieses Design.

Die Vorteile der Verwaltung von Registrierungen aus dem Back-End umfassen die Möglichkeit, Tags zu Registrierungen zu ändern, auch wenn die entsprechende App auf dem Gerät inaktiv ist, und die Client-App zu authentifizieren, bevor ein Tag zur Registrierung hinzugefügt wird.

Beispielcode zum Registrieren mit einem Benachrichtigungshub aus einem Back-End mithilfe einer Installation

Das Clientgerät erhält weiterhin sein PNS-Handle und relevante Installationseigenschaften wie zuvor und ruft eine benutzerdefinierte API im Back-End auf, die die Registrierung ausführen und Tags autorisieren kann usw. Das Back-End kann das Notification Hub SDK für Back-End-Vorgänge nutzen.

Sie können die PATCH-Methode auch mit dem JSON-Patch Standard zum Aktualisieren der Installation verwenden.

// Initialize the Notification Hub
NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(listenConnString, hubName);

// Custom API on the backend
public async Task<HttpResponseMessage> Put(DeviceInstallation deviceUpdate)
{

    Installation installation = new Installation();
    installation.InstallationId = deviceUpdate.InstallationId;
    installation.PushChannel = deviceUpdate.Handle;
    installation.Tags = deviceUpdate.Tags;

    switch (deviceUpdate.Platform)
    {
        case "wns":
            installation.Platform = NotificationPlatform.Wns;
            break;
        case "apns":
            installation.Platform = NotificationPlatform.Apns;
            break;
        case "fcm":
            installation.Platform = NotificationPlatform.Fcm;
            break;
        default:
            throw new HttpResponseException(HttpStatusCode.BadRequest);
    }


    // In the backend we can control if a user is allowed to add tags
    //installation.Tags = new List<string>(deviceUpdate.Tags);
    //installation.Tags.Add("username:" + username);

    await hub.CreateOrUpdateInstallationAsync(installation);

    return Request.CreateResponse(HttpStatusCode.OK);
}

Beispielcode zum Registrieren mit einem Benachrichtigungshub aus einem Back-End mithilfe einer Registrierungs-ID

Über Ihr App-Back-End können Sie grundlegende CRUDS-Vorgänge für Registrierungen ausführen. Beispiel:

var hub = NotificationHubClient.CreateClientFromConnectionString("{connectionString}", "hubName");

// create a registration description object of the correct type, e.g.
var reg = new WindowsRegistrationDescription(channelUri, tags);

// Create
await hub.CreateRegistrationAsync(reg);

// Get by ID
var r = await hub.GetRegistrationAsync<RegistrationDescription>("id");

// update
r.Tags.Add("myTag");

// update on hub
await hub.UpdateRegistrationAsync(r);

// delete
await hub.DeleteRegistrationAsync(r);

Das Back-End muss die Parallelität zwischen Registrierungsupdates behandeln. Notification Hubs bietet optimistische Parallelitätssteuerung für die Registrierungsverwaltung. Auf HTTP-Ebene wird dies mit der Verwendung von ETag für Registrierungsverwaltungsvorgänge implementiert. Dieses Feature wird transparent von Microsoft-SDKs verwendet, die eine Ausnahme auslösen, wenn ein Update aus Parallelitätsgründen abgelehnt wird. Das App-Back-End ist dafür verantwortlich, diese Ausnahmen zu behandeln und bei Bedarf das Update erneut auszuführen.