Gestione delle registrazioniRegistration management

PanoramicaOverview

In questo argomento viene illustrato come registrare i dispositivi con gli hub di notifica al fine di ricevere notifiche push.This topic explains how to register devices with notification hubs in order to receive push notifications. Vengono descritte le registrazioni a livello generale, quindi sono presentati i due modelli principali per la registrazione dei dispositivi: la registrazione dal dispositivo direttamente nell'hub di notifica e la registrazione tramite un back-end dell'applicazione.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.

Che cos'è la registrazione di un dispositivoWhat is device registration

La registrazione del dispositivo con un hub di notifica viene eseguita tramite una registrazione o un'installazione.Device registration with a Notification Hub is accomplished using a Registration or Installation.

RegistrazioniRegistrations

La registrazione associa l'handle del servizio di notifica della piattaforma (PNS) per un dispositivo con tag ed eventualmente un modello.A registration associates the Platform Notification Service (PNS) handle for a device with tags and possibly a template. L'handle PNS può essere un valore di ChannelURI, un token di dispositivo o un ID di registrazione GCM. I tag vengono usati per instradare le notifiche al set corretto di handle di dispositivo.The PNS handle could be a ChannelURI, device token, or GCM registration id. Tags are used to route notifications to the correct set of device handles. Per altre informazioni, vedere Routing ed espressioni tag.For more information, see Routing and Tag Expressions. I modelli vengono usati per implementare una trasformazione a livello di singola registrazione.Templates are used to implement per-registration transformation. Per altre informazioni, vedere Modelli.For more information, see Templates.

InstallazioniInstallations

Un'installazione è una registrazione avanzata che include un contenitore di proprietà correlate al push.An Installation is an enhanced registration that includes a bag of push related properties. È comunque l'approccio migliore e più recente alla registrazione dei dispositivi.It is the latest and best approach to registering your devices. Tuttavia, non è supportato dall’SDK .NET lato client (SDK dell’hub di notifica per le operazioni di back-end), per adesso.However, it is not supported by client side .NET SDK (Notification Hub SDK for backend operations) as of yet. Questo significa che in caso di registrazione dal dispositivo client stesso, è necessario utilizzare l’approccio API REST hub di notifica per supportare le installazioni.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. Se si utilizza un servizio di back-end, è possibile utilizzare l’ SDK dell’hub di notifica per le operazioni di back-end.If you are using a backend service, you should be able to use Notification Hub SDK for backend operations.

Ecco alcuni vantaggi chiave dell'uso delle installazioni:The following are some key advantages to using installations:

  • La creazione o l'aggiornamento di un'installazione è completamente idempotente.Creating or updating an installation is fully idempotent. È quindi possibile riprovare a eseguire l'operazione senza preoccuparsi di registrazioni duplicate.So you can retry it without any concerns about duplicate registrations.
  • Il modello di installazione semplifica l'esecuzione di singoli push destinati a un dispositivo specifico.The installation model makes it easy to do individual pushes - targeting specific device. Un tag di sistema "$InstallationId:[installationId]" viene aggiunto automaticamente con ogni registrazione basata su un'installazione.A system tag "$InstallationId:[installationId]" is automatically added with each installation based registration. È quindi possibile chiamare un'operazione di invio a questo tag per fare riferimento a un dispositivo specifico senza dover scrivere codice aggiuntivo.So you can call a send to this tag to target a specific device without having to do any additional coding.
  • L'uso delle installazioni consente inoltre di eseguire aggiornamenti parziali delle registrazioni.Using installations also enables you to do partial registration updates. L'aggiornamento parziale di un'installazione è richiesto con un metodo PATCH che usa lo standard JSON-Patch.The partial update of an installation is requested with a PATCH method using the JSON-Patch standard. Questo è particolarmente utile quando si desidera aggiornare i tag nella registrazione.This is particularly useful when you want to update tags on the registration. Non è necessario disattivare l'intera registrazione e quindi inviare di nuovo tutti i tag precedenti.You don't have to pull down the entire registration and then resend all the previous tags again.

Un'installazione può contenere le proprietà seguenti.An installation can contain the the following properties. Per un elenco completo delle proprietà di installazione, vedere Creare o sovrascrivere un'installazione con API REST o Proprietà Installation.For a complete listing of the installation properties see, Create or Overwrite an Installation with REST API or Installation Properties for the .

// 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: [] }
            }
        }
    }
}

È importante notare che le registrazioni e le installazioni non scadono più per impostazione predefinita.It is important to note that registrations and installations by default no longer expire.

Le registrazioni e le installazioni devono contenere un handle PNS valido per ogni dispositivo/canale.Registrations and installations must contain a valid PNS handle for each device/channel. Poiché gli handle PNS possono essere ottenuti solo in un'app client sul dispositivo, un modello consiste nell'eseguire la registrazione direttamente sul dispositivo con l'app client.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. D'altra parte, le considerazioni sulla sicurezza e la logica di business relativa ai tag potrebbero richiedere di gestire la registrazione del dispositivo nel back-end dell'app.On the other hand, security considerations and business logic related to tags might require you to manage device registration in the app back-end.

ModelliTemplates

Se si desidera usare modelli, l'installazione del dispositivo contiene anche tutti i modelli associati al dispositivo in un formato JSON (vedere l'esempio precedente).If you want to use Templates, the device installation also hold all templates associated with that device in a JSON format (see sample above). I nomi dei modelli consentono di usare diversi modelli per lo stesso dispositivo.The template names help target different templates for the same device.

Si noti che il nome di ogni modello è associato al corpo di un modello e a un set di tag facoltativo.Note that each template name maps to a template body and an optional set of tags. Inoltre, ogni piattaforma può avere ulteriori proprietà del modello.Moreover, each platform can have additional template properties. Per Windows Store (che usa WNS) e Windows Phone 8 (che usa MPNS), un set di intestazioni aggiuntivo può far parte del modello.For Windows Store (using WNS) and Windows Phone 8 (using MPNS), an additional set of headers can be part of the template. Nel caso degli APN, è possibile impostare una proprietà di scadenza su una costante o un'espressione del modello.In the case of APNs, you can set an expiry property to either a constant or to a template expression. Per un elenco completo delle proprietà di installazione, vedere l'argomento Creare o sovrascrivere un'installazione con REST .For a complete listing of the installation properties see, Create or Overwrite an Installation with REST topic.

Riquadri secondari per le app di Windows StoreSecondary Tiles for Windows Store Apps

Per le applicazioni client di Windows Store, inviare notifiche ai riquadri secondari equivale a inviarle a quello primario.For Windows Store client applications, sending notifications to secondary tiles is the same as sending them to the primary one. Questo è supportato anche nelle installazioni.This is also supported in installations. Si noti che i riquadri secondari hanno un diverso ChannelUri, che viene gestito in modo trasparente dall'SDK nell'app client.Note that secondary tiles have a different ChannelUri, which the SDK on your client app handles transparently.

Il dizionario SecondaryTiles usa lo stesso TileId che viene usato per creare l'oggetto SecondaryTiles nell'app di Windows Store.The SecondaryTiles dictionary uses the same TileId that is used to create the SecondaryTiles object in your Windows Store app. Come nel caso del valore ChannelUri primario, i valori ChannelUri dei riquadri secondari possono cambiare in qualsiasi momento.As with the primary ChannelUri, ChannelUris of secondary tiles can change at any moment. Per mantenere aggiornate le installazioni nell'hub di notifica, il dispositivo deve aggiornarle con i valori ChannelUri correnti dei riquadri secondari.In order to keep the installations in the notification hub updated, the device must refresh them with the current ChannelUris of the secondary tiles.

Gestione delle registrazioni dal dispositivoRegistration management from the device

Quando si gestisce la registrazione del dispositivo dalle app client, il back-end è responsabile solo dell'invio delle notifiche.When managing device registration from client apps, the backend is only responsible for sending notifications. Le app client mantengono aggiornati gli handle PNS e registrano i tag.Client apps keep PNS handles up to date, and register tags. Questo modello è illustrato nell'immagine seguente.The following picture illustrates this pattern.

Il dispositivo recupera l'handle PNS dal PNS, quindi esegue la registrazione direttamente con l'hub di notifica.The device first retrieves the PNS handle from the PNS, then registers with the notification hub directly. Una volta che la registrazione ha esito positivo, il back-end dell'app può inviare una notifica relativa alla registrazione.After the registration is successful, the app backend can send a notification targeting that registration. Per altre informazioni su come inviare le notifiche, vedere Routing ed espressioni tag.For more information about how to send notifications, see Routing and Tag Expressions. Si noti che in questo caso si useranno solo i diritti Listen per accedere agli hub di notifica dal dispositivo.Note that in this case, you will use only Listen rights to access your notification hubs from the device. Per altre informazioni, vedere Sicurezza.For more information, see Security.

La registrazione dal dispositivo è il metodo più semplice, ma presenta alcuni svantaggi.Registering from the device is the simplest method, but it has some drawbacks. Il primo svantaggio è che un'app client può aggiornare solo i propri tag quando l'app è attiva.The first drawback is that a client app can only update its tags when the app is active. Ad esempio, se un utente dispone di due dispositivi che registrano tag relativi a squadre sportive, quando il primo dispositivo esegue la registrazione per un ulteriore tag (ad esempio, i Seahawk), il secondo dispositivo non riceverà le notifiche relative ai Seahawk finché l'app nel secondo dispositivo non viene eseguita una seconda volta.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. Più in generale, quando i tag interessano più dispositivi, la gestione dei tag dal back-end rappresenta una soluzione migliore.More generally, when tags are affected by multiple devices, managing tags from the backend is a desirable option. Il secondo svantaggio della gestione delle registrazioni dall'app client è che, poiché le applicazioni possono essere oggetto di un attacco, proteggere la registrazione tramite tag specifici richiede particolare attenzione, come illustrato nella sezione "Sicurezza a livello di tag".The second drawback of registration management from the client app is that, since apps can be hacked, securing the registration to specific tags requires extra care, as explained in the section “Tag-level security.”

Codice di esempio per la registrazione con un hub di notifica da un dispositivo tramite un'installazioneExample code to register with a notification hub from a device using an installation

Al momento, questa operazione è supportata solo tramite l' API REST degli hub di notifica.At this time, this is only supported using the Notification Hubs REST API.

È inoltre possibile usare il metodo PATCH tramite lo standard JSON-Patch per l'aggiornamento dell'installazione.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 a 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();
}

Codice di esempio per la registrazione con un hub di notifica da un dispositivo tramite una registrazioneExample code to register with a notification hub from a device using a registration

Questi metodi creano o aggiornano una registrazione per il dispositivo in cui vengono chiamati.These methods create or update a registration for the device on which they are called. Ciò significa che, per aggiornare l'handle o i tag, è necessario sovrascrivere l'intera registrazione.This means that in order to update the handle or the tags, you must overwrite the entire registration. Tenere presente che le registrazioni sono temporanee, quindi è necessario disporre sempre di un archivio affidabile con i tag correnti necessari per il dispositivo specifico.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");
}

Gestione delle registrazioni da un back-endRegistration management from a backend

La gestione delle registrazioni dal back-end richiede la scrittura di codice aggiuntivo.Managing registrations from the backend requires writing additional code. L'app dal dispositivo deve fornire l'handle PNS aggiornato al back-end a ogni avvio dell'app (insieme ai tag e ai modelli) e il back-end deve aggiornare tale handle nell'hub di notifica.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. Questa progettazione è illustrata nell'immagine seguente.The following picture illustrates this design.

I vantaggi della gestione delle registrazioni dal back-end includono la possibilità di modificare i tag delle registrazioni anche quando l'app corrispondente nel dispositivo è inattiva e di autenticare l'app client prima di aggiungere un tag alla relativa registrazione.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.

Codice di esempio per la registrazione con un hub di notifica da un back-end tramite un'installazioneExample code to register with a notification hub from a backend using an installation

Il dispositivo client ottiene ancora il relativo handle PNS e le proprietà di installazione rilevanti come prima e chiama un'API personalizzata nel back-end che può eseguire la registrazione, autorizzare i tag e così via. Il back-end può sfruttare l'SDK degli hub di notifica per le operazioni di back-end.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.

È inoltre possibile usare il metodo PATCH tramite lo standard JSON-Patch per l'aggiornamento dell'installazione.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 "gcm":
            installation.Platform = NotificationPlatform.Gcm;
            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);
}

Codice di esempio per la registrazione con un hub di notifica da un dispositivo tramite un ID di registrazioneExample code to register with a notification hub from a device using a registration id

Dal back-end dell'app è possibile eseguire operazioni CRUD di base sulle registrazioni.From your app backend, you can perform basic CRUDS operations on registrations. Ad esempio: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);

Il back-end deve gestire la concorrenza tra gli aggiornamenti delle registrazioni.The backend must handle concurrency between registration updates. Il bus di servizio offre il controllo della concorrenza ottimistica per la gestione delle registrazioni.Service Bus offers optimistic concurrency control for registration management. A livello HTTP, questo viene implementato attraverso l'uso di ETag sulle operazioni di gestione delle registrazioni.At the HTTP level, this is implemented with the use of ETag on registration management operations. Questa funzionalità viene usata in modo trasparente dagli SDK Microsoft, che generano un'eccezione se un aggiornamento viene rifiutato a causa della concorrenza.This feature is transparently used by Microsoft SDKs, which throw an exception if an update is rejected for concurrency reasons. Il backend dell'app è responsabile della gestione di queste eccezioni e dei nuovi tentativi di aggiornamento, se necessario.The app backend is responsible for handling these exceptions and retrying the update if required.