Registreringshantering

Det här avsnittet beskriver hur du registrerar enheter med meddelandehubbar för att ta emot push-meddelanden. Avsnittet beskriver registreringar på hög nivå och introducerar sedan de två huvudsakliga mönstren för registrering av enheter: registrering från enheten direkt till meddelandehubben och registrering via en programserverdel.

Vad är enhetsregistrering?

Enhetsregistrering med en Notification Hub utförs med hjälp av en registrering eller installation.

Registreringar

En registrering associerar PNS-handtag (Platform Notification Service) för en enhet med taggar och eventuellt en mall. PNS-referensen kan vara en ChannelURI eller registrerings-ID för enhetstoken. Taggar används för att dirigera meddelanden till rätt uppsättning enhetshandtag. Mer information finns i Routning och tagguttryck. Mallar används för att implementera transformering per registrering. Mer information finns i Mallar.

Installationer

En installation är en förbättrad registrering som innehåller en påse med push-relaterade egenskaper. Det är den senaste och bästa metoden för att registrera dina enheter med hjälp av .NET SDK på serversidan (Notification Hub SDK för serverdelsåtgärder). Du kan också använda REST API-metoden för Notification Hubs för att registrera installationer på själva klientenheten. Om du använder en serverdelstjänst bör du kunna använda Notification Hub SDK för serverdelsåtgärder.

Följande är några viktiga fördelar med att använda installationer:

• Det är helt idempotent att skapa eller uppdatera en installation. Så du kan försöka igen utan att behöva bekymra dig om dubbletter av registreringar.
• Installationsmodellen stöder ett särskilt taggformat ($InstallationId:{INSTALLATION_ID}) som gör det möjligt att skicka ett meddelande direkt till den specifika enheten. Om appens kod till exempel anger ett installations-ID joe93developer för den här enheten kan en utvecklare rikta in sig på den här enheten när de skickar ett meddelande till taggen $InstallationId:{joe93developer} . På så sätt kan du rikta in dig på en specifik enhet utan att behöva göra någon ytterligare kodning.
• Med hjälp av installationer kan du också göra partiella registreringsuppdateringar. Den partiella uppdateringen av en installation begärs med en PATCH-metod med hjälp av JSON-Patch-standarden. Detta är användbart när du vill uppdatera taggarna för registreringen. Du behöver inte hämta hela registreringen och sedan skicka alla tidigare taggar igen.

En installation kan innehålla följande egenskaper. En fullständig lista över installationsegenskaperna finns i Skapa eller skriv över en installation med REST API eller Installationsegenskaper.

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

Registreringar och installationer måste innehålla ett giltigt PNS-handtag för varje enhet/kanal. Eftersom PNS-referenser endast kan hämtas i en klientapp på enheten är ett mönster att registrera direkt på enheten med klientappen. Å andra sidan kan säkerhetsöverväganden och affärslogik som rör taggar kräva att du hanterar enhetsregistrering i appens serverdel.

När push-överföringen görs till en referens som har upphört att gälla av PNS rensar Azure Notification Hubs automatiskt den associerade installations-/registreringsposten baserat på det svar som tas emot från PNS-servern. Om du vill rensa utgångna poster från en sekundär meddelandehubb lägger du till anpassad logik som bearbetar feedback från varje sändning. Upphör sedan att installera/registrera i den sekundära meddelandehubben.

Mallar

Om du vill använda mallar innehåller enhetsinstallationen även alla mallar som är associerade med enheten i JSON-format (se exemplet ovan). Mallnamnen hjälper dig att rikta olika mallar för samma enhet.

Varje mallnamn mappar till en malltext och en valfri uppsättning taggar. Dessutom kan varje plattform ha ytterligare mallegenskaper. För Windows Store (med WNS) kan ytterligare en uppsättning rubriker ingå i mallen. När det gäller APN:er kan du ange en förfalloegenskap till antingen en konstant eller ett malluttryck. En fullständig lista över installationsegenskaperna finns i avsnittet Skapa eller skriva över en installation med REST .

Sekundära paneler för Windows Store-appar

För Windows Store-klientprogram är det samma sak att skicka meddelanden till sekundära paneler som att skicka dem till den primära. Detta stöds också i installationer. Sekundära paneler har en annan ChannelUri, som SDK:n i klientappen hanterar transparent.

SecondaryTiles-ordlistan använder samma TileId som används för att skapa SecondaryTiles-objektet i din Windows Store-app. Precis som med den primära ChannelUri kan ChannelUris för sekundära paneler ändras när som helst. För att hålla installationerna i meddelandehubben uppdaterade måste enheten uppdatera dem med aktuella ChannelUris för de sekundära panelerna.

Registreringshantering från enheten

När du hanterar enhetsregistrering från klientappar ansvarar serverdelen endast för att skicka meddelanden. Klientappar håller PNS-handtag uppdaterade och registrerar taggar. Följande bild illustrerar det här mönstret.

Enheten hämtar först PNS-referensen från PNS och registreras sedan direkt med meddelandehubben. När registreringen har slutförts kan appens serverdel skicka ett meddelande för registreringen. Mer information om hur du skickar meddelanden finns i Routning och tagguttryck.

I det här fallet använder du bara lyssnarrättigheter för att få åtkomst till dina meddelandehubbar från enheten. Mer information finns i Säkerhet.

Registrering från enheten är den enklaste metoden, men den har några nackdelar:

• En klientapp kan bara uppdatera sina taggar när appen är aktiv. Om en användare till exempel har två enheter som registrerar taggar relaterade till sportlag, när den första enheten registrerar sig för en ytterligare tagg (till exempel Seahawks), får den andra enheten inte meddelanden om Seahawks förrän appen på den andra enheten körs en andra gång. Mer allmänt är det önskvärt att hantera taggar från serverdelen när taggar påverkas av flera enheter.
• Eftersom appar kan hackas kräver skydd av registreringen till specifika taggar extra försiktighet, enligt beskrivningen i artikeln Säkerhet.

Exempelkod för att registrera med en meddelandehubb från en enhet med hjälp av en installation

För närvarande stöds detta endast med hjälp av Notification Hubs REST API.

Du kan också använda PATCH-metoden med JSON-Patch-standarden för att uppdatera installationen.

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

Exempelkod för att registrera med en meddelandehubb från en enhet med hjälp av en registrering

De här metoderna skapar eller uppdaterar en registrering för enheten som de anropas på. Det innebär att du måste skriva över hela registreringen för att kunna uppdatera referensen eller taggarna. Kom ihåg att registreringar är tillfälliga, så du bör alltid ha ett tillförlitligt lager med de aktuella taggarna som en specifik enhet behöver.

// 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");
}

Registreringshantering från en serverdel

Hantering av registreringar från serverdelen kräver att ytterligare kod skrivs. Appen från enheten måste tillhandahålla den uppdaterade PNS-referensen till serverdelen varje gång appen startar (tillsammans med taggar och mallar), och serverdelen måste uppdatera handtaget på meddelandehubben. Följande bild illustrerar den här designen.

Fördelarna med att hantera registreringar från serverdelen är bland annat möjligheten att ändra taggar till registreringar även när motsvarande app på enheten är inaktiv och att autentisera klientappen innan du lägger till en tagg i registreringen.

Exempelkod för att registrera med en meddelandehubb från en serverdel med hjälp av en installation

Klientenheten får fortfarande sin PNS-referens och relevanta installationsegenskaper som tidigare och anropar ett anpassat API på serverdelen som kan utföra registreringen och auktorisera taggar osv. Serverdelen kan använda Notification Hub SDK för serverdelsåtgärder.

Du kan också använda PATCH-metoden med JSON-Patch-standarden för att uppdatera installationen.

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

Exempelkod för att registrera med en meddelandehubb från en serverdel med hjälp av ett registrerings-ID

Från appens serverdel kan du utföra grundläggande CRUDS-åtgärder på registreringar. Exempel:

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

Serverdelen måste hantera samtidighet mellan registreringsuppdateringar. Service Bus erbjuder optimistisk samtidighetskontroll för registreringshantering. På HTTP-nivå implementeras detta med ETag för registreringsåtgärder. Den här funktionen används transparent av Microsoft SDK:er, vilket utlöser ett undantag om en uppdatering avvisas av samtidighetsskäl. Appens serverdel ansvarar för att hantera dessa undantag och försöka uppdatera igen om det behövs.