Zarządzanie rejestracją

W tym temacie opisano sposób rejestrowania urządzeń za pomocą centrów powiadomień w celu odbierania powiadomień wypychanych. W temacie opisano rejestracje na wysokim poziomie, a następnie przedstawiono dwa główne wzorce rejestrowania urządzeń: rejestrowanie z urządzenia bezpośrednio do centrum powiadomień i rejestrowanie za pośrednictwem zaplecza aplikacji.

Co to jest rejestracja urządzenia

Rejestracja urządzenia w centrum powiadomień jest realizowana przy użyciu rejestracji lub instalacji.

Rejestracje

Rejestracja kojarzy uchwyt usługi powiadomień platformy (PNS) dla urządzenia z tagami i ewentualnie szablonem. Dojście pnS może być identyfikatorem ChannelURI lub identyfikatorem rejestracji tokenu urządzenia. Tagi służą do kierowania powiadomień do poprawnego zestawu dojść urządzeń. Aby uzyskać więcej informacji, zobacz Routing i wyrażenia tagów. Szablony służą do implementowania transformacji na rejestrację. Aby uzyskać więcej informacji, zobacz Szablony.

Uwaga

Usługa Azure Notification Hubs obsługuje maksymalnie 60 tagów na urządzenie.

Instalacje

Instalacja to rozszerzona rejestracja obejmująca torbę właściwości powiązanych z wypychaniem. Jest to najnowsze i najlepsze podejście do rejestrowania urządzeń przy użyciu zestawu SDK platformy .NET po stronie serwera (zestaw SDK usługi Notification Hub na potrzeby operacji zaplecza). Możesz również użyć podejścia interfejsu API REST usługi Notification Hubs do rejestrowania instalacji na urządzeniu klienckim. Jeśli używasz usługi zaplecza, możesz użyć zestawu SDK usługi Notification Hub na potrzeby operacji zaplecza.

Poniżej przedstawiono niektóre kluczowe zalety korzystania z instalacji:

• Tworzenie lub aktualizowanie instalacji jest w pełni idempotentne. Dlatego możesz ponowić próbę bez obaw o zduplikowane rejestracje.
• Model instalacji obsługuje specjalny format tagu ($InstallationId:{INSTALLATION_ID}), który umożliwia wysyłanie powiadomienia bezpośrednio do określonego urządzenia. Jeśli na przykład kod aplikacji ustawia identyfikator instalacji dla tego konkretnego joe93developer urządzenia, deweloper może kierować to urządzenie podczas wysyłania powiadomienia do tagu $InstallationId:{joe93developer} . Dzięki temu można kierować określone urządzenie bez konieczności wykonywania dodatkowego kodowania.
• Korzystanie z instalacji umożliwia również wykonywanie częściowych aktualizacji rejestracji. Częściowa aktualizacja instalacji jest żądana przy użyciu metody PATCH przy użyciu standardu JSON-Patch. Jest to przydatne, gdy chcesz zaktualizować tagi rejestracji. Nie musisz ściągać całej rejestracji, a następnie ponownie ponownie wysłać wszystkie poprzednie tagi.

Instalacja może zawierać następujące właściwości. Aby uzyskać pełną listę właściwości instalacji, zobacz Tworzenie lub zastępowanie instalacji przy użyciu interfejsu API REST lub właściwości instalacji.

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

Uwaga

Domyślnie rejestracje i instalacje nie wygasają.

Rejestracje i instalacje muszą zawierać prawidłowy uchwyt pnS dla każdego urządzenia/kanału. Ponieważ uchwyty pnS można uzyskać tylko w aplikacji klienckiej na urządzeniu, jednym ze wzorców jest zarejestrowanie się bezpośrednio na tym urządzeniu za pomocą aplikacji klienckiej. Z drugiej strony zagadnienia dotyczące zabezpieczeń i logika biznesowa związane z tagami mogą wymagać zarządzania rejestracją urządzeń w zapleczu aplikacji.

Gdy wypychanie zostanie wykonane do dojścia, które wygasło przez usługę PNS, usługa Azure Notification Hubs automatycznie czyści skojarzony rekord instalacji/rejestracji na podstawie odpowiedzi otrzymanej z serwera PNS. Aby wyczyścić wygasłe rekordy z pomocniczego centrum powiadomień, dodaj niestandardową logikę, która przetwarza opinie z każdego wysyłania. Następnie wygaśnie instalację/rejestrację w pomocniczym centrum powiadomień.

Uwaga

Interfejs API instalacji nie obsługuje usługi Baidu (mimo że interfejs API rejestracji działa).

Szablony

Jeśli chcesz użyć szablonów, instalacja urządzenia przechowuje również wszystkie szablony skojarzone z tym urządzeniem w formacie JSON (zobacz przykład powyżej). Nazwy szablonów ułatwiają określanie różnych szablonów dla tego samego urządzenia.

Każda nazwa szablonu mapuje treść szablonu i opcjonalny zestaw tagów. Ponadto każda platforma może mieć dodatkowe właściwości szablonu. W przypadku Sklepu Windows (korzystającego z usługi WNS) dodatkowy zestaw nagłówków może być częścią szablonu. W przypadku sieci APNs można ustawić właściwość wygaśnięcia na stałą lub na wyrażenie szablonu. Aby uzyskać pełną listę właściwości instalacji, zobacz Tworzenie lub zastępowanie instalacji przy użyciu tematu REST.

Kafelki pomocnicze dla aplikacji ze Sklepu Windows

W przypadku aplikacji klienckich ze Sklepu Windows wysyłanie powiadomień do kafelków pomocniczych jest takie samo, jak wysyłanie ich do podstawowej. Jest to również obsługiwane w instalacjach. Kafelki pomocnicze mają inny identyfikator ChannelUri, który zestaw SDK w aplikacji klienckiej obsługuje w sposób niewidoczny.

Słownik SecondaryTiles używa tego samego identyfikatora TileId, który służy do tworzenia obiektu SecondaryTiles w aplikacji ze Sklepu Windows. Podobnie jak w przypadku podstawowego identyfikatora ChannelUris kafelków pomocniczych mogą ulec zmianie w dowolnym momencie. Aby instalacje w centrum powiadomień były aktualizowane, urządzenie musi odświeżyć je przy użyciu bieżących identyfikatorów ChannelUris kafelków pomocniczych.

Zarządzanie rejestracją z urządzenia

Podczas zarządzania rejestracją urządzeń z aplikacji klienckich zaplecze jest odpowiedzialne tylko za wysyłanie powiadomień. Aplikacje klienckie zapewniają aktualność usługi PNS i rejestrują tagi. Na poniższej ilustracji przedstawiono ten wzorzec.

Urządzenie najpierw pobiera uchwyt pnS z usługi PNS, a następnie rejestruje się bezpośrednio w centrum powiadomień. Po pomyślnym zakończeniu rejestracji zaplecze aplikacji może wysłać powiadomienie przeznaczone dla tej rejestracji. Aby uzyskać więcej informacji na temat wysyłania powiadomień, zobacz Routing and Tag Expressions (Wyrażenia routingu i tagów).

W takim przypadku używasz tylko praw nasłuchiwania w celu uzyskania dostępu do centrów powiadomień z urządzenia. Aby uzyskać więcej informacji, zobacz Zabezpieczenia.

Rejestrowanie z urządzenia jest najprostszą metodą, ale ma pewne wady:

• Aplikacja kliencka może aktualizować tagi tylko wtedy, gdy aplikacja jest aktywna. Jeśli na przykład użytkownik ma dwa urządzenia, które rejestrują tagi związane z zespołami sportowymi, gdy pierwsze urządzenie zarejestruje się na potrzeby dodatkowego tagu (na przykład Seahawks), drugie urządzenie nie otrzyma powiadomień o seahawks, dopóki aplikacja na drugim urządzeniu nie zostanie wykonana po raz drugi. Ogólnie rzecz biorąc, gdy tagi mają wpływ na wiele urządzeń, zarządzanie tagami z zaplecza jest pożądaną opcją.
• Ponieważ aplikacje mogą zostać zhakowane, zabezpieczenie rejestracji do określonych tagów wymaga dodatkowej opieki, jak wyjaśniono w artykule Zabezpieczenia.

Przykładowy kod do zarejestrowania się w centrum powiadomień z urządzenia przy użyciu instalacji

Obecnie jest to obsługiwane tylko przy użyciu interfejsu API REST usługi Notification Hubs.

Można również użyć metody PATCH przy użyciu standardu JSON-Patch do aktualizowania instalacji.

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

Przykładowy kod do zarejestrowania się w centrum powiadomień z urządzenia przy użyciu rejestracji

Te metody tworzą lub aktualizują rejestrację urządzenia, na którym są wywoływane. Oznacza to, że aby zaktualizować uchwyt lub tagi, należy zastąpić całą rejestrację. Pamiętaj, że rejestracje są przejściowe, dlatego zawsze należy mieć niezawodny magazyn z bieżącymi tagami, których potrzebuje określone urządzenie.

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

Zarządzanie rejestracją z zaplecza

Zarządzanie rejestracjami z zaplecza wymaga pisania dodatkowego kodu. Aplikacja z urządzenia musi podać zaktualizowaną dojścia pnS do zaplecza za każdym razem, gdy aplikacja jest uruchamiana (wraz z tagami i szablonami), a zaplecze musi zaktualizować ten uchwyt w centrum powiadomień. Na poniższej ilustracji przedstawiono ten projekt.

Zalety zarządzania rejestracjami z zaplecza obejmują możliwość modyfikowania tagów do rejestracji nawet wtedy, gdy odpowiednia aplikacja na urządzeniu jest nieaktywna, oraz uwierzytelnianie aplikacji klienckiej przed dodaniem tagu do jego rejestracji.

Przykładowy kod do zarejestrowania się w centrum powiadomień z zaplecza przy użyciu instalacji

Urządzenie klienckie nadal pobiera obsługę systemu powiadomień i odpowiednie właściwości instalacji, tak jak wcześniej i wywołuje niestandardowy interfejs API na zapleczu, który może wykonywać rejestrację i autoryzować tagi itp. Zaplecze może korzystać z zestawu SDK usługi Notification Hub na potrzeby operacji zaplecza.

Można również użyć metody PATCH przy użyciu standardu JSON-Patch do aktualizowania instalacji.

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

Przykładowy kod do zarejestrowania się w centrum powiadomień z zaplecza przy użyciu identyfikatora rejestracji

Z poziomu zaplecza aplikacji możesz wykonywać podstawowe operacje CRUDS na rejestracjach. Przykład:

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

Zaplecze musi obsługiwać współbieżność między aktualizacjami rejestracji. Usługa Service Bus oferuje optymistyczną kontrolę współbieżności na potrzeby zarządzania rejestracją. Na poziomie HTTP jest to implementowane przy użyciu narzędzia ETag w operacjach zarządzania rejestracją. Ta funkcja jest w przezroczysty sposób używana przez zestawy SDK firmy Microsoft, co zgłasza wyjątek, jeśli aktualizacja została odrzucona ze względów współbieżności. Zaplecze aplikacji jest odpowiedzialne za obsługę tych wyjątków i ponawianie próby aktualizacji w razie potrzeby.