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átjoe93developer
, 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.