Správa registrací

Toto téma vysvětluje, jak zaregistrovat zařízení v centrech oznámení, aby bylo možné přijímat nabízená oznámení. Téma popisuje registrace na vysoké úrovni a pak představuje dva hlavní vzory pro registraci zařízení: registraci ze zařízení přímo do centra oznámení a registraci prostřednictvím back-endu aplikace.

Co je registrace zařízení?

Registrace zařízení v centru oznámení se provádí pomocí registrace nebo instalace.

Registrace

Registrace přidruží popisovač služby Oznámení platformy (PNS) zařízení ke značkám a případně šabloně. Popisovač systému PNS může být Identifikátor ChannelURI nebo ID registrace tokenu zařízení. Značky se používají ke směrování oznámení na správnou sadu popisovačů zařízení. Další informace najdete v tématu Směrování a označování výrazů. Šablony se používají k implementaci transformace podle registrace. Další informace najdete v tématu Šablony.

Poznámka

Azure Notification Hubs podporuje maximálně 60 značek na zařízení.

Instalace

Instalace je vylepšená registrace, která obsahuje sadu vlastností souvisejících s nasdílením změn. Jedná se o nejnovější a nejlepší přístup k registraci zařízení pomocí sady .NET SDK na straně serveru (sada SDK centra oznámení pro back-endové operace). K registraci instalací na samotném klientském zařízení můžete použít také přístup s rozhraním REST API služby Notification Hubs . Pokud používáte back-endovou službu, měli byste být schopni používat sadu SDK centra oznámení pro back-endové operace.

Tady jsou některé klíčové výhody používání instalací:

• Vytvoření nebo aktualizace instalace je plně idempotentní. Takže to můžete zkusit znovu, aniž byste se museli zabývat duplicitními registracemi.
• Instalační model podporuje speciální formát značky ($InstallationId:{INSTALLATION_ID}), který umožňuje odeslat oznámení přímo do konkrétního zařízení. Pokud například kód aplikace nastaví ID joe93developer instalace pro toto konkrétní zařízení, může vývojář při odesílání oznámení do značky $InstallationId:{joe93developer} zacílit toto zařízení. Díky tomu můžete cílit na konkrétní zařízení, aniž byste museli provádět další kódování.
• Pomocí instalací můžete také provádět částečné aktualizace registrace. Částečná aktualizace instalace se vyžaduje pomocí metody PATCH s využitím standardu JSON-Patch. To je užitečné, když chcete aktualizovat značky při registraci. Nemusíte stahovat dolů celou registraci a pak znovu odeslat všechny předchozí značky.

Instalace může obsahovat následující vlastnosti. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace pomocí rozhraní REST API nebo Vlastnosti instalace.

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

Poznámka

Ve výchozím nastavení platnost registrací a instalací nevyprší.

Registrace a instalace musí obsahovat platný popisovač systému PNS pro každé zařízení nebo kanál. Vzhledem k tomu, že popisovače systému PNS je možné získat pouze v klientské aplikaci na zařízení, jedním ze vzorů je registrace přímo na daném zařízení s klientskou aplikací. Na druhou stranu bezpečnostní aspekty a obchodní logika související se značkami můžou vyžadovat správu registrace zařízení v back-endu aplikace.

Když se oznámení odešle do popisovače, jehož platnost vypršela systémem PNS, Azure Notification Hubs automaticky vyčistí přidružený záznam instalace nebo registrace na základě odpovědi přijaté ze serveru PNS. Pokud chcete vyčistit záznamy s vypršenou platností ze sekundárního centra oznámení, přidejte vlastní logiku, která zpracovává zpětnou vazbu z každého odeslání. Pak v sekundárním centru oznámení ukončete platnost instalace nebo registrace.

Poznámka

Rozhraní API pro instalaci nepodporuje službu Baidu (i když rozhraní API Registrations ano).

Šablony

Pokud chcete použít šablony, instalace zařízení obsahuje také všechny šablony přidružené k danému zařízení ve formátu JSON (viz ukázka výše). Názvy šablon pomáhají cílit na různé šablony pro stejné zařízení.

Každý název šablony se mapuje na tělo šablony a volitelnou sadu značek. Každá platforma navíc může mít další vlastnosti šablony. Pro Windows Store (pomocí WNS) může být součástí šablony další sada hlaviček. V případě služby APNs můžete nastavit vlastnost vypršení platnosti na konstantu nebo na výraz šablony. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace pomocí REST .

Sekundární dlaždice pro aplikace pro Windows Store

U klientských aplikací pro Windows Store je odesílání oznámení na sekundární dlaždice stejné jako odesílání na primární dlaždici. To je také podporováno v instalacích. Sekundární dlaždice mají jiný identifikátor ChannelUri, který sada SDK ve vaší klientské aplikaci transparentně zpracovává.

Slovník SecondaryTiles používá stejné TileId, které se používá k vytvoření objektu SecondaryTiles v aplikaci pro Windows Store. Stejně jako u primárního Identifikátoru ChannelUri se můžou identifikátory ChannelUri sekundárních dlaždic kdykoli změnit. Aby bylo možné udržovat instalace v centru oznámení aktualizované, musí je zařízení aktualizovat aktuálními identifikátory ChannelUris sekundárních dlaždic.

Správa registrací ze zařízení

Při správě registrace zařízení z klientských aplikací zodpovídá back-end jenom za odesílání oznámení. Klientské aplikace udržují obslužné rutiny systému PNS aktuální a registrují značky. Tento model znázorňuje následující obrázek.

Zařízení nejprve načte popisovač systému PNS z systému PNS a pak se zaregistruje přímo v centru oznámení. Po úspěšné registraci může back-end aplikace odeslat oznámení, které cílí na danou registraci. Další informace o odesílání oznámení najdete v tématu Směrování a výrazy značek.

V tomto případě pro přístup k centru oznámení ze zařízení používáte pouze práva naslouchacího procesu. Další informace najdete v tématu Zabezpečení.

Registrace ze zařízení je nejjednodušší metoda, má ale některé nevýhody:

• Klientská aplikace může aktualizovat své značky, jenom když je aplikace aktivní. Pokud má uživatel například dvě zařízení, která registrují značky související se sportovními týmy, když si první zařízení zaregistruje další značku (například Seahawks), druhé zařízení nebude dostávat oznámení o Seahawks, dokud se aplikace na druhém zařízení nespustí podruhé. Obecněji platí, že pokud jsou značky ovlivněné více zařízeními, je správa značek z back-endu žádoucí možností.
• Vzhledem k tomu, že aplikace mohou být napadeny hackerem, zabezpečení registrace pro konkrétní značky vyžaduje zvláštní péči, jak je vysvětleno v článku Zabezpečení.

Příklad kódu pro registraci v centru oznámení ze zařízení pomocí instalace

V tuto chvíli se to podporuje jenom pomocí rozhraní REST API služby Notification Hubs.

K aktualizaci instalace můžete použít také metodu PATCH s použitím standardu JSON-Patch .

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

Příklad kódu pro registraci v centru oznámení ze zařízení pomocí registrace

Tyto metody vytvoří nebo aktualizují registraci zařízení, na kterém se volají. To znamená, že pokud chcete aktualizovat popisovač nebo značky, musíte přepsat celou registraci. Mějte na paměti, že registrace jsou přechodné, takže byste vždy měli mít spolehlivé úložiště s aktuálními značkami, které konkrétní zařízení potřebuje.

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

Správa registrací z back-endu

Správa registrací z back-endu vyžaduje psaní dalšího kódu. Aplikace ze zařízení musí back-endu poskytnout aktualizovaný popisovač systému PNS při každém spuštění aplikace (spolu se značkami a šablonami) a back-end musí tento popisovač aktualizovat v centru oznámení. Tento návrh znázorňuje následující obrázek.

Mezi výhody správy registrací z back-endu patří možnost upravovat značky registrací, i když je odpovídající aplikace na zařízení neaktivní, a ověření klientské aplikace před přidáním značky do registrace.

Příklad kódu pro registraci v centru oznámení z back-endu pomocí instalace

Klientské zařízení stále získává popisovač systému PNS a relevantní vlastnosti instalace jako předtím a volá vlastní rozhraní API na back-endu, které může provádět registraci, autorizaci značek atd. Back-end může k back-endovým operacím využít sadu SDK centra oznámení.

K aktualizaci instalace můžete použít také metodu PATCH s použitím standardu JSON-Patch .

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

Příklad kódu pro registraci v centru oznámení z back-endu pomocí ID registrace

Z back-endu aplikace můžete u registrací provádět základní operace CRUDS. Příklad:

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

Back-end musí zpracovávat souběžnost mezi aktualizacemi registrace. Service Bus nabízí optimistické řízení souběžnosti pro správu registrací. Na úrovni PROTOKOLU HTTP se to implementuje s použitím značky ETag v operacích správy registrace. Tuto funkci transparentně používají sady Microsoft SDK, které vyvolají výjimku, pokud je aktualizace odmítnuta z důvodu souběžnosti. Back-end aplikace zodpovídá za zpracování těchto výjimek a opakování aktualizace v případě potřeby.