Regisztrációkezelés

Ez a témakör azt ismerteti, hogyan regisztrálhat eszközöket az értesítési központokkal a leküldéses értesítések fogadása érdekében. A témakör magas szinten ismerteti a regisztrációkat, majd bemutatja az eszközök regisztrálásának két fő mintáját: az eszközről való regisztrálást közvetlenül az értesítési központba, és az alkalmazás háttérrendszerén keresztül történő regisztrálást.

Mi az eszközregisztráció?

A Notification Hubon történő eszközregisztráció regisztrációja regisztrációval vagy telepítéssel történik.

Regisztrációk

A regisztráció a platformértesítési szolgáltatás (PNS) leíróját társítja egy eszközhöz címkékkel és esetleg sablonnal. A PNS-leíró lehet ChannelURI vagy eszközjogkivonat regisztrációs azonosítója. A címkék segítségével az értesítéseket a megfelelő eszközleírókhoz irányíthatja. További információ: Útválasztási és címkekifejezések. A sablonok a regisztrációnkénti átalakítás implementálásához használhatók. További információért lásd a Sablonok szakaszt.

Megjegyzés

Az Azure Notification Hubs eszközönként legfeljebb 60 címkét támogat.

Telepítések

A telepítés egy továbbfejlesztett regisztráció, amely egy zsák leküldéses kapcsolódó tulajdonságot tartalmaz. Ez a legújabb és legjobb módszer az eszközök kiszolgálóoldali .NET SDK(Notification Hub SDK háttérműveletekhez) használatával történő regisztrálására. A Notification Hubs REST API-megközelítéssel is regisztrálhatja a telepítéseket az ügyféleszközön. Ha háttérszolgáltatást használ, használhatja a Notification Hub SDK-t a háttérműveletekhez.

A telepítések használatának néhány fő előnye a következő:

• A telepítés létrehozása vagy frissítése teljes mértékben idempotens. Így újrapróbálkozás nélkül próbálkozhat a duplikált regisztrációkkal kapcsolatban.
• A telepítési modell egy speciális címkeformátumot ($InstallationId:{INSTALLATION_ID}) támogat, amely lehetővé teszi az értesítések közvetlen küldését az adott eszközre. Ha például az alkalmazás kódja beállítja az adott eszköz telepítési azonosítóját joe93developer , a fejlesztő megcélzhatja ezt az eszközt, amikor értesítést küld a $InstallationId:{joe93developer} címkének. Ez lehetővé teszi egy adott eszköz megcélzását anélkül, hogy további kódolást kellene végeznie.
• A telepítések használatával részleges regisztrációs frissítéseket is elvégezhet. A rendszer a telepítés részleges frissítését egy PATCH metódussal kéri a JSON-Patch szabvány használatával. Ez akkor hasznos, ha frissíteni szeretné a címkéket a regisztráción. Nem kell lekérnie a teljes regisztrációt, majd újra el kell adnia az összes előző címkét.

A telepítés a következő tulajdonságokat tartalmazhatja. A telepítési tulajdonságok teljes listáját lásd: Telepítés létrehozása vagy felülírása REST API-val vagy telepítési tulajdonságokkal.

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

Megjegyzés

Alapértelmezés szerint a regisztrációk és telepítések nem járnak le.

A regisztrációknak és a telepítéseknek érvényes PNS-leírót kell tartalmazniuk az egyes eszközökhöz/csatornákhoz. Mivel a PNS-leírók csak az eszközön található ügyfélalkalmazásban szerezhetők be, az egyik minta az, hogy közvetlenül az adott eszközön regisztrál az ügyfélalkalmazással. A címkékhez kapcsolódó biztonsági szempontok és üzleti logika azonban szükségessé teheti az eszközregisztráció kezelését az alkalmazás háttérrendszerében.

Ha a leküldés a PNS által lejárt leíróra történik, az Azure Notification Hubs automatikusan törli a társított telepítési/regisztrációs rekordot a PNS-kiszolgálótól kapott válasz alapján. Ha a lejárt rekordokat egy másodlagos értesítési központból szeretné törölni, adjon hozzá egyéni logikát, amely az egyes küldések visszajelzéseit dolgozza fel. Ezután lejár a telepítés/regisztráció a másodlagos értesítési központban.

Megjegyzés

Az Install API nem támogatja a Baidu szolgáltatást (bár a Registrations API igen).

Sablonok

Ha sablonokat szeretne használni, az eszköz telepítése az eszközhöz társított összes sablont JSON formátumban is tartalmazza (lásd a fenti mintát). A sablonnevek segítenek különböző sablonokat célozni ugyanahhoz az eszközhöz.

Minden sablonnév egy sablontörzsre és egy választható címkekészletre képez le. Emellett minden platform további sablontulajdonságokat is tartalmazhat. A Windows Áruházban (a WNS használatával) további fejléckészletek is lehetnek a sablon részei. APN-k esetén a lejárati tulajdonságot konstansra vagy sablonkifejezésre állíthatja be. A telepítési tulajdonságok teljes listáját lásd: Telepítés létrehozása vagy felülírása REST-lel című témakör.

Másodlagos csempék Windows Áruházbeli alkalmazásokhoz

Windows Áruházbeli ügyfélalkalmazások esetén az értesítések küldése a másodlagos csempékre ugyanaz, mint az elsődleges csempére való küldés. Ez a telepítésekben is támogatott. A másodlagos csempék eltérő ChannelUri-kkal rendelkeznek, amelyeket az ügyfélalkalmazás SDK-ja transzparensen kezel.

A SecondaryTiles szótár ugyanazt a TileId azonosítót használja, amelyet a SecondaryTiles objektum létrehozásához használ a Windows Áruházbeli alkalmazásban. Az elsődleges ChannelUri-okhoz hasonlóan a másodlagos csempék ChannelUri-jai is bármikor változhatnak. Az értesítési központban lévő telepítések naprakészen tartása érdekében az eszköznek frissítenie kell őket a másodlagos csempék aktuális ChannelUri-jaival.

Regisztrációkezelés az eszközről

Az eszközregisztráció ügyfélalkalmazásokból történő kezelésekor a háttérrendszer csak az értesítések küldéséért felelős. Az ügyfélalkalmazások naprakészen tartják a PNS-kezelőket, és regisztrálják a címkéket. Az alábbi képen ez a minta látható.

Az eszköz először lekéri a PNS-leírót a PNS-ből, majd közvetlenül regisztrál az értesítési központban. A regisztráció sikerességét követően az alkalmazás háttérrendszere értesítést küldhet a regisztrációról. Az értesítések küldéséről további információt az Útválasztás és címkekifejezések című témakörben talál.

Ebben az esetben csak a Figyelés jogosultságokkal fér hozzá az értesítési központokhoz az eszközről. További információ: Biztonság.

Az eszközről történő regisztráció a legegyszerűbb módszer, de hátrányai vannak:

• Az ügyfélalkalmazások csak akkor tudják frissíteni a címkéket, ha az alkalmazás aktív. Ha például egy felhasználó két olyan eszközzel rendelkezik, amelyek a sportcsapatokhoz kapcsolódó címkéket regisztrálnak, amikor az első eszköz regisztrál egy további címkét (például Seahawks), a második eszköz nem kapja meg a Seahawksról szóló értesítéseket, amíg a második eszközön futó alkalmazást nem hajtják végre másodszor. Általánosságban elmondható, hogy ha a címkéket több eszköz is érinti, a címkék háttérrendszerből való kezelése kívánatos lehetőség.
• Mivel az alkalmazások feltörhetők, a regisztráció adott címkékre való biztonságossá tétele különös figyelmet igényel, amint azt a Biztonság című cikk ismerteti.

Példakód egy eszköz értesítési központjával való regisztrációhoz egy telepítéssel

Ez jelenleg csak a Notification Hubs REST API-val támogatott.

A telepítés frissítéséhez a PATCH metódust is használhatja a JSON-Patch szabvány használatával.

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éldakód egy eszköz értesítési központjával való regisztrációhoz regisztrációval

Ezek a metódusok létrehoznak vagy frissítenek egy regisztrációt ahhoz az eszközhöz, amelyen meghívják őket. Ez azt jelenti, hogy a leíró vagy a címkék frissítéséhez felül kell írnia a teljes regisztrációt. Ne feledje, hogy a regisztrációk átmenetiek, ezért mindig megbízható tárolóval kell rendelkeznie az adott eszközhöz szükséges aktuális címkékkel.

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

Regisztrációkezelés háttérrendszerből

A háttérrendszer regisztrációinak kezeléséhez további kódot kell írni. Az eszközről származó alkalmazásnak minden indításkor meg kell adnia a frissített PNS-leírót a háttérrendszernek (címkékkel és sablonokkal együtt), és a háttérrendszernek frissítenie kell ezt a leírót az értesítési központban. Az alábbi kép ezt a tervet szemlélteti.

A háttérrendszer regisztrációinak kezelésének előnyei közé tartozik a címkék regisztrációkra való módosítása akkor is, ha az eszközön lévő megfelelő alkalmazás inaktív, valamint az ügyfélalkalmazás hitelesítése, mielőtt címkét ad a regisztrációhoz.

Példakód egy értesítési központtal való regisztrációhoz egy háttérrendszerből egy telepítés használatával

Az ügyféleszköz a korábbiakhoz hasonlóan továbbra is megkapja a PNS-leírót és a megfelelő telepítési tulajdonságokat, és meghív egy egyéni API-t a háttérrendszeren, amely képes elvégezni a regisztrációt és engedélyezni a címkéket stb. A háttérrendszer a Notification Hub SDK-t használhatja háttérműveletekhez.

A telepítés frissítéséhez a PATCH metódust is használhatja a JSON-Patch szabvány használatával.

// 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éldakód egy értesítési központtal való regisztrációhoz egy háttérrendszerből regisztrációs azonosító használatával

Az alkalmazás háttérrendszerében alapszintű CRUDS-műveleteket hajthat végre a regisztrációkon. Például:

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

A háttérrendszernek kezelnie kell a regisztrációs frissítések közötti egyidejűséget. A Service Bus optimista egyidejűségi vezérlést biztosít a regisztráció kezeléséhez. Ez HTTP-szinten az ETag regisztrációkezelési műveletekre való használatával valósul meg. Ezt a funkciót a Microsoft SDK-k transzparensen használják, ami kivételt jelent, ha egy frissítést egyidejűségi okokból elutasítanak. Az alkalmazás háttérrendszere felelős a kivételek kezeléséért és szükség esetén a frissítés újrapróbálkozásáért.