RegistrierungsverwaltungRegistration management

In diesem Thema wird erläutert, wie Geräte bei Notification Hubs registriert werden, um Pushbenachrichtigungen zu empfangen.This topic explains how to register devices with notification hubs in order to receive push notifications. Nach einem allgemeinen Überblick über Registrierungen werden in diesem Thema die beiden Hauptmuster zum Registrieren von Geräten vorgestellt: die direkte Registrierung beim Notification Hub über das Gerät und die Registrierung über ein Anwendungs-Back-End.The topic describes registrations at a high level, then introduces the two main patterns for registering devices: registering from the device directly to the notification hub, and registering through an application backend.

Was ist die Geräteregistrierung?What is device registration

Die Geräteregistrierung bei einem Notification Hub erfolgt mithilfe einer Registrierung oder Installation.Device registration with a Notification Hub is accomplished using a Registration or Installation.

RegistrierungenRegistrations

Bei einer Registrierung wird das PNS-Handle (Platform Notification Service) für ein Gerät Tags und ggf. einer Vorlage zugeordnet.A registration associates the Platform Notification Service (PNS) handle for a device with tags and possibly a template. Das PNS-Handle könnte einem ChannelURI, einem Gerätetoken oder einer FCM-Registrierungs-ID entsprechen.The PNS handle could be a ChannelURI, device token, or FCM registration ID. Tags werden verwendet, um Benachrichtigungen an die richtige Gruppe von Gerätehandles weiterzuleiten.Tags are used to route notifications to the correct set of device handles. Weitere Informationen finden Sie unter Weiterleitung und Tagausdrücke.For more information, see Routing and Tag Expressions. Vorlagen werden verwendet, um Transformationen pro Registrierung zu implementieren.Templates are used to implement per-registration transformation. Weitere Informationen finden Sie unter Vorlagen.For more information, see Templates.

Hinweis

Azure Notification Hubs unterstützt maximal 60 Tags pro Gerät.Azure Notification Hubs supports a maximum of 60 tags per device.

InstallationenInstallations

Eine Installation ist eine erweiterte Registrierung, die einen Behälter von Eigenschaften umfasst, die sich auf Pushvorgänge beziehen.An Installation is an enhanced registration that includes a bag of push related properties. Dies ist der neueste und beste Ansatz zum Registrieren Ihrer Geräte.It is the latest and best approach to registering your devices. Bisher wird er jedoch noch nicht vom clientseitigen .NET SDK (Notification Hub-SDK für Back-End-Vorgänge) unterstützt.However, it is not supported by client-side .NET SDK (Notification Hub SDK for backend operations) as of yet. Wenn Sie die Registrierung über das Client-Gerät selbst durchführen, müssen Sie daher die Notification Hubs-REST-API zur Unterstützung von Installationen verwenden.This means if you are registering from the client device itself, you would have to use the Notification Hubs REST API approach to support installations. Wenn Sie einen Back-End-Dienst verwenden, sollten Sie auch das Notification Hub-SDK für Back-End-Vorgängeverwenden können.If you are using a backend service, you should be able to use Notification Hub SDK for backend operations.

Im Folgenden sind die wichtigsten Vorteile bei der Verwendung von Installationen beschrieben:The following are some key advantages to using installations:

  • Das Erstellen oder Aktualisieren einer Installation ist vollständig idempotent.Creating or updating an installation is fully idempotent. Sie können eine Installation wiederholen, ohne sich um doppelte Registrierungen sorgen zu müssen.So you can retry it without any concerns about duplicate registrations.
  • Das Installationsmodell unterstützt ein spezielles Tagformat ($InstallationId:{INSTALLATION_ID}), das das direkte Senden von Benachrichtigungen an das spezifische Gerät ermöglicht.The installation model supports a special tag format ($InstallationId:{INSTALLATION_ID}) that enables sending a notification directly to the specific device. Wenn der Code der App beispielsweise eine Installations-ID von joe93developer für dieses spezifische Gerät zulässt, kann ein Entwickler dieses Gerät als Ziel zum Senden einer Benachrichtigung an das $InstallationId:{joe93developer}-Tag verwenden.For example, if the app's code sets an installation ID of joe93developer for this particular device, a developer can target this device when sending a notification to the $InstallationId:{joe93developer} tag. So können Sie ein spezifisches Gerät als Ziel verwenden, ohne zusätzlichen Code schreiben zu müssen.This enables you to target a specific device without having to do any additional coding.
  • Mithilfe von Installationen können Sie zudem Registrierungsteilupdates durchführen.Using installations also enables you to do partial registration updates. Das Teilupdate einer Installation wird mit einer PATCH-Methode unter Verwendung des JSON-Patch-Standardsangefordert.The partial update of an installation is requested with a PATCH method using the JSON-Patch standard. Dies ist nützlich, wenn Sie Tags für die Registrierung aktualisieren möchten.This is useful when you want to update tags on the registration. Sie müssen nicht die gesamte Registrierung auflösen und dann alle vorherigen Tags erneut senden.You don't have to pull down the entire registration and then resend all the previous tags again.

Eine Installation kann folgende Eigenschaften enthalten.An installation can contain the following properties. Eine vollständige Liste der Installationseigenschaften finden Sie unter Erstellen oder Überschreiben einer Installation mit der REST-API oder Installationseigenschaften.For a complete listing of the installation properties, see Create or Overwrite an Installation with REST API or Installation Properties.

// 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.By default, registrations and installations do not expire.

Registrierungen und Installationen müssen ein gültiges PNS-Handle für jedes Gerät bzw. jeden Kanal enthalten.Registrations and installations must contain a valid PNS handle for each device/channel. Da PNS-Handles nur in einer Client-App auf dem Gerät abgerufen werden können, besteht ein Muster darin, sich direkt auf dem Gerät mit der Client-App zu registrieren.Because PNS handles can only be obtained in a client app on the device, one pattern is to register directly on that device with the client app. Andererseits können tagbezogene Sicherheitsaspekte und Geschäftslogik die Verwaltung der Geräteregistrierung im App-Back-End erforderlich machen.On the other hand, security considerations and business logic related to tags might require you to manage device registration in the app back-end.

Hinweis

Der Baidu-Dienst wird von der Registrierungs-API, nicht aber von der Installations-API unterstützt.The Installations API does not support the Baidu service (although the Registrations API does).

VorlagenTemplates

Wenn Sie Vorlagenverwenden möchten, sollte die Geräteinstallation auch alle Vorlagen, die dem jeweiligen Gerät zugeordnet sind, in einem JSON-Format enthalten (siehe Beispiel oben).If you want to use Templates, the device installation also holds all templates associated with that device in a JSON format (see sample above). Mithilfe der Vorlagennamen können unterschiedliche Vorlagen problemlos auf dasselbe Gerät abzielen.The template names help target different templates for the same device.

Jeder Vorlagenname ist einem Vorlagentext und einer optionalen Gruppe von Tags zugeordnet.Each template name maps to a template body and an optional set of tags. Darüber hinaus kann jede Plattform zusätzliche Vorlageneigenschaften aufweisen.Moreover, each platform can have additional template properties. Für den Windows Store (mit WNS) und Windows Phone 8 (mit MPNS) kann die Vorlage einen zusätzlichen Satz von Headern enthalten.For Windows Store (using WNS) and Windows Phone 8 (using MPNS), an additional set of headers can be part of the template. Bei APNs können Sie eine Ablaufeigenschaft auf eine Konstante oder auf einen Vorlagenausdruck festlegen.In the case of APNs, you can set an expiry property to either a constant or to a template expression. Eine vollständige Liste der Installationseigenschaften finden Sie im Thema Erstellen oder Überschreiben einer Installation mit REST .For a complete listing of the installation properties see, Create or Overwrite an Installation with REST topic.

Sekundäre Kacheln für Windows Store-AppsSecondary Tiles for Windows Store Apps

Für Windows Store-Clientanwendungen ist das Senden von Benachrichtigungen an sekundäre Kacheln und an die primäre Kachel identisch.For Windows Store client applications, sending notifications to secondary tiles is the same as sending them to the primary one. Dies wird auch in Installationen unterstützt.This is also supported in installations. Sekundäre Kacheln verfügen über einen unterschiedlichen ChannelUri, der vom SDK in der Client-App transparent behandelt wird.Secondary tiles have a different ChannelUri, which the SDK on your client app handles transparently.

Das SecondaryTiles-Wörterbuch verwendet dieselbe TileId, die zum Erstellen des SecondaryTiles-Objekts in der Windows Store-App verwendet wird.The SecondaryTiles dictionary uses the same TileId that is used to create the SecondaryTiles object in your Windows Store app. Wie beim primären ChannelUri können sich ChannelUris sekundärer Kacheln jederzeit ändern.As with the primary ChannelUri, ChannelUris of secondary tiles can change at any moment. Damit die Installationen im Notification Hub aktuell bleiben, müssen sie vom Gerät mit den aktuellen ChannelUris der sekundären Kacheln aktualisiert werden.In order to keep the installations in the notification hub updated, the device must refresh them with the current ChannelUris of the secondary tiles.

Registrierungsverwaltung über das GerätRegistration management from the device

Wenn die Geräteregistrierung über Client-Apps verwaltet wird, ist das Back-End nur für das Senden von Benachrichtigungen verantwortlich.When managing device registration from client apps, the backend is only responsible for sending notifications. Client-Apps sorgen dafür, dass PNS-Handles auf dem neuesten Stand bleiben, und registrieren Tags.Client apps keep PNS handles up-to-date, and register tags. Dieses Muster wird in der folgenden Abbildung veranschaulicht.The following picture illustrates this pattern.

Registrierung auf dem Gerät

Zuerst ruft das Gerät das PNS-Handle aus dem PNS ab und registriert sich dann direkt beim Notification Hub.The device first retrieves the PNS handle from the PNS, then registers with the notification hub directly. Wenn die Registrierung erfolgreich verläuft, kann das App-Back-End eine zielgerichtete Benachrichtigung an diese Registrierung senden.After the registration is successful, the app backend can send a notification targeting that registration. Weitere Informationen zum Senden von Benachrichtigungen finden Sie unter Weiterleitung und Tagausdrücke.For more information about how to send notifications, see Routing and Tag Expressions.

In diesem Fall verwenden Sie nur Lauschrechte, um über das Gerät auf die Notification Hubs zuzugreifen.In this case, you use only Listen rights to access your notification hubs from the device. Weitere Informationen finden Sie unter Sicherheit.For more information, see Security.

Die Registrierung über das Gerät ist die einfachste Methode, birgt aber auch Nachteile:Registering from the device is the simplest method, but it has some drawbacks:

  • Eine Client-App kann ihre Tags nur aktualisieren, wenn die App aktiv ist.A client app can only update its tags when the app is active. Angenommen, ein Benutzer verfügt über zwei Geräte, die Tags im Zusammenhang mit Sportmannschaften registrieren. Wenn sich das erste Gerät für ein zusätzliches Tag (z. B. Borussia Dortmund) registriert, empfängt das zweite Gerät erst Benachrichtigungen zu Borussia Dortmund, wenn die App auf dem zweiten Gerät ein zweites Mal ausgeführt wird.For example, if a user has two devices that register tags related to sport teams, when the first device registers for an additional tag (for example, Seahawks), the second device will not receive the notifications about the Seahawks until the app on the second device is executed a second time. Allgemeiner ausgedrückt bedeutet dies, dass die Verwaltung von Tags möglichst über das Back-End erfolgen sollte, wenn Tags für mehrere Geräte gelten.More generally, when tags are affected by multiple devices, managing tags from the backend is a desirable option.
  • Da Apps gehackt werden können, muss die Registrierung mit besonderer Sorgfalt auf bestimmte Tags beschränkt werden (wie im Artikel Sicherheit erläutert).Since apps can be hacked, securing the registration to specific tags requires extra care, as explained in the article Security.

Beispielcode zur Registrierung bei einem Notification Hub über ein Gerät mithilfe einer InstallationExample code to register with a notification hub from a device using an installation

Momentan wird dieser Vorgang nur bei Verwendung der Notification Hubs-REST-APIunterstützt.At this time, this is only supported using the Notification Hubs REST API.

Die Installation kann auch mit der PATCH-Methode unter Verwendung des JSON-Patch-Standards aktualisiert werden.You can also use the PATCH method using the JSON-Patch standard for updating the installation.

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 (https://msdn.microsoft.com/library/azure/dn495627.aspx)
        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 ===
        // See https://msdn.microsoft.com/library/azure/dn495627.aspx
        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 have not stored 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 RegistrierungExample code to register with a notification hub from a device using a registration

Durch diese Methoden wird eine Registrierung für das Gerät erstellt oder aktualisiert, auf dem sie aufgerufen werden.These methods create or update a registration for the device on which they are called. Dies bedeutet, dass zum Aktualisieren des Handles oder der Tags die gesamte Registrierung überschrieben werden muss.This means that in order to update the handle or the tags, you must overwrite the entire registration. Wie bereits erwähnt, sind Registrierungen temporär. Daher sollten die aktuellen Tags, die ein bestimmtes Gerät benötigt, immer an einem zuverlässigen Ort gespeichert sein.Remember that registrations are transient, so you should always have a reliable store with the current tags that a specific device needs.

// 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 have not stored 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 über ein Back-EndRegistration management from a backend

Zum Verwalten von Registrierungen über das Back-End muss zusätzlicher Code geschrieben werden.Managing registrations from the backend requires writing additional code. 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.The app from the device must provide the updated PNS handle to the backend every time the app starts (along with tags and templates), and the backend must update this handle on the notification hub. Dieses Verfahren wird in der folgenden Abbildung veranschaulicht.The following picture illustrates this design.

Registrierungsverwaltung

Die Vorteile der Verwaltung von Registrierungen über das Back-End liegen darin, dass Tags für Registrierungen selbst dann geändert werden können, wenn die entsprechende App auf dem Gerät inaktiv ist, und dass die Client-App authentifiziert werden kann, bevor ihrer Registrierung ein Tag hinzugefügt wird.The advantages of managing registrations from the backend include the ability to modify tags to registrations even when the corresponding app on the device is inactive, and to authenticate the client app before adding a tag to its registration.

Beispielcode zur Registrierung bei einem Notification Hub über ein Back-End mithilfe einer InstallationExample code to register with a notification hub from a backend using an installation

Das Clientgerät ruft sein PNS-Handle und die relevanten Installationseigenschaften wie zuvor ab 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.The client device still gets its PNS handle and relevant installation properties as before and calls a custom API on the backend that can perform the registration and authorize tags etc. The backend can leverage the Notification Hub SDK for backend operations.

Die Installation kann auch mit der PATCH-Methode unter Verwendung des JSON-Patch-Standards aktualisiert werden.You can also use the PATCH method using the JSON-Patch standard for updating the installation.

// 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 "mpns":
            installation.Platform = NotificationPlatform.Mpns;
            break;
        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 zur Registrierung bei einem Notification Hub über ein Gerät mithilfe einer Registrierungs-IDExample code to register with a notification hub from a device using a registration ID

Über das App-Back-End können Sie grundlegende CRUDS-Vorgänge für Registrierungen ausführen.From your app backend, you can perform basic CRUDS operations on registrations. Beispiele:For example:

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

Die Nebenläufigkeit zwischen Registrierungsupdates muss vom Back-End behandelt werden.The backend must handle concurrency between registration updates. Service Bus unterstützt die Steuerung für optimistische Nebenläufigkeit für die Registrierungsverwaltung.Service Bus offers optimistic concurrency control for registration management. Auf der HTTP-Ebene wird dies durch die Verwendung von ETag für Registrierungsverwaltungsvorgänge implementiert.At the HTTP level, this is implemented with the use of ETag on registration management operations. Dieses Feature wird von Microsoft-SDKs, die eine Ausnahme auslösen, wenn ein Update aus Gründen der Nebenläufigkeit abgelehnt wird, transparent verwendet.This feature is transparently used by Microsoft SDKs, which throw an exception if an update is rejected for concurrency reasons. Das Back-End ist dafür verantwortlich, diese Ausnahmen zu behandeln und das Update zu wiederholen, sofern erforderlich.The app backend is responsible for handling these exceptions and retrying the update if necessary.