Regisztrációkezelés

Ez a cikk bemutatja, hogyan regisztrálhat eszközöket az Azure Notification Hubsban leküldéses értesítések fogadása érdekében. A cikk a regisztrációkat magas szinten ismerteti, 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 egy alkalmazás háttérrendszerén keresztül történő regisztrációt.

Mi az eszközregisztráció?

A Notification Hubon történő eszközregisztráció 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ó. 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óért lásd: Útválasztás é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ó: Sablonok.

Megjegyzés

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

Létesítmények

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

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

• A telepítés létrehozása vagy annak frissítése teljes mértékben idempotens. A duplikált regisztrációkkal kapcsolatos aggodalmak nélkül újrapróbálkozhat.
• A telepítési modell egy speciális címkeformátumot ($InstallationId:{INSTALLATION_ID}) támogat, amely lehetővé teszi, hogy közvetlenül az adott eszközre küldjön értesítést. 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ésekkel részleges regisztrációs frissítéseket is elvégezhet. A telepítés részleges frissítését patch metódussal, a JSON-Patch szabvány használatával kéri a rendszer. Ez a módszer akkor hasznos, ha frissíteni szeretné a címkéket a regisztráción. Nem kell letöltenie a teljes regisztrációt, majd újraküldenie az összes korábbi címkét.

A telepítés a következő tulajdonságokat tartalmazhatja. A telepítési tulajdonságok teljes listáját a REST API- vagy telepítési tulajdonságokkal rendelkező telepítés létrehozása vagy felülírása című témakörben találhatja meg.

// 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 a 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 lévő ügyfélalkalmazásban szerezhetők be, az egyik megoldás az, hogy közvetlenül az adott eszközön az ügyfélalkalmazással regisztrálunk. A címkékhez kapcsolódó biztonsági megfontolások és üzleti logika azonban szükségessé teheti az eszközregisztráció kezelését az alkalmazás háttérrendszerében.

Amikor a leküldés egy olyan kezelőfelületre történik, amelyet a PNS lejártnak jelölt, az Azure Notification Hubs automatikusan törli a válaszreakció alapján a társított telepítési vagy regisztrációs bejegyzést, amelyet a PNS-kiszolgáló küldött. Ha lejárt rekordokat szeretne megtisztítani egy másodlagos értesítési központból, adjon hozzá egyéni logikát, amely feldolgozza az egyes küldések visszajelzéseit. Ezután lejár a telepítés/regisztráció a másodlagos értesítési központban.

Megjegyzés

A telepítési API-k nem támogatják a Baidu szolgáltatást (bár a regisztrációs 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 az előző szakaszban található mintát). A sablonnevek segítenek különböző sablonokat célozni ugyanahhoz az eszközhöz.

Minden sablonnév egy sablontörzshöz és egy választható címkekészlethez társul. Minden platform további sablontulajdonságokat is tartalmazhat. APN-k esetén a lejárati tulajdonságot konstansra vagy sablonkifejezésre is beállíthatja. A telepítési tulajdonságok teljes listájáért lásd: Telepítés létrehozása vagy felülírása REST-témakörrel .

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

Windows Áruházbeli ügyfélalkalmazások esetén az értesítések másodlagos csempékre való küldése 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-ekhez 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 frissítéséhez az eszköznek a másodlagos csempék aktuális ChannelUris-jaival kell frissítenie őket.

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

Az ügyfélalkalmazások eszközregisztrációjának kezelésekor a háttérrendszer csak az értesítések küldéséért felelős. Az ügyfélalkalmazások megtartják a PNS-kezelőket up-to-date és a címkék regisztrálását. 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özponthoz. A regisztráció sikeres befejezése után az alkalmazás háttérrendszere küldhet egy értesítést, amely a regisztrációt célozza. Az értesítések küldéséhez további információt az Útválasztás és a 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ókért lásd a Biztonságszakaszt.

Az eszközről való 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ére (például Seahawksra), 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 hajtja 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 történő kezelése kívánatos lehetőség.
• Mivel az alkalmazások feltörhetők, a regisztráció adott címkékre történő biztonságossá tétele további ápolást igényel, amint azt a Biztonság című cikk ismerteti.

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

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

Példakód egy értesítési központtal való regisztrációhoz egy eszközről regisztrációval

Ezek a metódusok létrehoznak vagy frissítenek egy regisztrációt annak az eszköznek, amelyen meghívják őket. Ez azt jelenti, hogy az azonosító vagy a címkék frissítéséhez újra 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 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");
}

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 meg kell adnia a frissített PNS-leírót a háttérrendszernek minden alkalommal, amikor az alkalmazás elindul (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épen ez a terv látható.

A háttérrendszer regisztrációinak kezelésének előnyei közé tartozik a címkék regisztrációra való módosítása akkor is, ha az eszközön lévő megfelelő alkalmazás inaktív, és 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 Notification Hubs optimista egyidejűségi vezérlést biztosít a regisztrációkezeléshez. A HTTP-szinten ez 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.