Správa registrací

Tento článek vysvětluje, jak registrovat zařízení ve službě Azure Notification Hubs, aby bylo možné přijímat nabízená oznámení. Článek popisuje registrace na vysoké úrovni a pak zavádí 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řiřadí identifikátor služby oznámení platformy (PNS) zařízení k tagům a případně také šabloně. Popisovač PNS může být ChannelURI identifikátor nebo ID registrace tokenu zařízení. Tagy slouží ke směrování notifikací na správnou sadu popisovačů zařízení. Další informace najdete v tématu Směrování a značkové výrazy. Šablony se používají k implementaci transformace pro každou registraci zvlášť. Další informace najdete v tématu Šablony.

Poznámka:

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

Instalace

Instalace je rozšířená registrace, která zahrnuje sadu vlastností souvisejících s push. 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 k rozhraní REST API služby Notification Hubs . Pokud používáte back-endovou službu, měli byste být schopni použít sadu Notification Hubs SDK pro back-endové operace.

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

• Vytvoření nebo aktualizace instalace je plně idempotentní. Můžete to zkusit znovu bez obav o duplicitní registrace.
• Instalační model podporuje speciální formát značek ($InstallationId:{INSTALLATION_ID}), který umožňuje odesílat oznámení přímo do konkrétního zařízení. Pokud například kód aplikace nastaví ID instalace joe93developer pro toto konkrétní zařízení, může vývojář zaměřit na toto zařízení při odesílání oznámení na tagu $InstallationId:{joe93developer}. Díky tomu můžete cílit na konkrétní zařízení, aniž byste museli provádět další kódování.
• Použití instalací také umožňuje provádět částečné aktualizace registrace. Částečná aktualizace instalace je požadována metodou PATCH pomocí JSON-Patch standardu. Tato metoda je užitečná, když chcete aktualizovat značky při registraci. Nemusíte stahovat celou registraci a pak znovu posílat 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 vlastností 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í nevyprší platnost registrací a instalací.

Registrace a instalace musí obsahovat platný identifikátor PNS pro každé zařízení a kanál. Vzhledem k tomu, že identifikátory PNS lze získat pouze v klientské aplikaci na zařízení, jedním ze způsobů je registrace přímo na daném zařízení pomocí klientské aplikace. Naproti tomu aspekty zabezpečení 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 na popisovač, jehož platnost vypršela kvůli PNS, Služba Azure Notification Hubs automaticky vyčistí přidružený záznam instalace/registrace podle odpovědi 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í. Potom vyprší platnost instalace/registrace v sekundárním centru oznámení.

Poznámka:

Rozhraní API pro instalace nepodporují službu Baidu (i když rozhraní API pro registraci 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 předchozí části). Názvy šablon pomáhají cílit na různé šablony pro stejné zařízení.

Každý název šablony se mapuje na obsah šablony a volitelnou sadu značek. Každá platforma může mít další vlastnosti šablony. V případě APNs můžete nastavit vlastnost vypršení platnosti buď na konstantu, nebo na výraz šablony. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace tématem REST .

Sekundární dlaždice pro aplikace Windows Store

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

Ve slovníku SecondaryTiles se používá stejný TileId, který se také používá k vytvoření objektu SecondaryTiles ve vaší aplikaci pro Windows Store. Stejně jako u primárního ChannelUri se ChannelUri sekundárních dlaždic mohou kdykoliv změnit. Aby instalace v centru oznámení byly udržovány aktuální, musí je zařízení obnovit s aktuálními URI kanálů sekundárních dlaždic.

Správa registrace ze zařízení

Při správě registrace zařízení z klientských aplikací zodpovídá back-end pouze za odesílání oznámení. Klientské aplikace udržují identifikátory PNS up-to-date a registrují tagy. Tento vzor znázorňuje následující obrázek.

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

V takovém případě použijete pouze práva k naslouchání pro přístup k centru oznámení ze zařízení. Další informace naleznete v tématu Zabezpečení.

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

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

Ukázkový kód 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 také použít metodu PATCH pomocí JSON-Patch standardu .

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

Ukázkový kód pro registraci v centru oznámení ze zařízení pomocí registrace

Tyto metody vytvoří nebo aktualizují registraci zařízení, na kterém jsou volány. To znamená, že pokud chcete aktualizovat popisovač nebo značky, musíte přepsat celou registraci. Nezapomeňte, že registrace jsou přechodné, takže vždy byste 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 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");
}

Správa registrace z back-endu

Správa registrací z back-endu vyžaduje napsání dalšího kódu. Aplikace z zařízení musí při každém spuštění poskytovat aktualizovaný popisovač PNS na backend (společně se značkami a šablonami) a backend tento popisovač musí 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 na registrace i v případě, že je odpovídající aplikace na zařízení neaktivní, a ověření klientské aplikace před přidáním značky do registrace.

Ukázkový kód pro registraci v centru oznámení z back-endu pomocí instalace

Klientské zařízení stále získává svůj popisovač PNS a relevantní vlastnosti instalace stejně jako dříve a volá vlastní rozhraní API na back-endu, které může provádět registraci a autorizovat značky a podobně. Back-end může využít sadu SDK centra oznámení pro provoz back-endu.

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

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

Ukázkový kód pro registraci v centru oznámení z back-endu pomocí ID registrace

Z back-endu aplikace můžete provádět základní operace CRUDS při registraci. Napří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. Notification Hubs nabízí optimistickou kontrolu souběžnosti pro správu registrace. Na úrovni HTTP se to implementuje s použitím značky ETag při operacích správy registrace. Tato funkce je transparentně používána sadami MICROSOFT SDK, která vyvolá výjimku, pokud je aktualizace odmítnuta z důvodů souběžnosti. Back-end aplikace zodpovídá za zpracování těchto výjimek a v případě potřeby zkusí aktualizaci zopakovat.