إدارة التسجيل

يشرح هذا الموضوع كيفية تسجيل الأجهزة باستخدام مراكز الإعلامات من أجل تلقي الإعلامات المنبثقة. يصف الموضوع التسجيلات على مستوى عال، ثم يقدم النمطين الرئيسيين لتسجيل الأجهزة: التسجيل من الجهاز مباشرة إلى مركز الإعلام، والتسجيل من خلال خلفية التطبيق.

ما المقصود بتسجيل الجهاز

يتم إنجاز تسجيل الجهاز باستخدام مركز الإعلامات باستخدام التسجيل أو التثبيت.

التسجيلات

يقرن التسجيل مؤشر «خدمة إعلام النظام الأساسي» (PNS) لجهاز بعلامات وربما قالب. يمكن أن يكون مقبض PNS هو ChannelURI أو معرف تسجيل الرمز المميز للجهاز. تستخدم العلامات لتوجيه الإعلامات إلى المجموعة الصحيحة من مؤشرات الجهاز. للمزيد من المعلومات، راجع التوجيه وتعبيرات العلامات. يتم استخدام القوالب لتنفيذ تحويل كل تسجيل. لمزيدٍ من المعلومات، راجع Templates.

ملاحظة

تدعم Azure Notification Hubs 60 علامة كحد أقصى لكل جهاز.

عمليات التثبيت

التثبيت هو تسجيل محسن يتضمن حقيبة من الخصائص المتعلقة بالدفع. إنه أحدث وأفضل نهج لتسجيل أجهزتك باستخدام ‎.NET SDK من جانب الخادم (Notification Hub SDK لعمليات الواجهة الخلفية). يمكنك أيضاً استخدام نهج واجهة برمجة تطبيقات REST لمراكز الإعلامات لتسجيل التثبيتات على جهاز العميل نفسه. إذا كنت تستخدم خدمة خلفية، يجب أن تكون قادرا على استخدام Notification Hub SDK لعمليات الواجهة الخلفية.

فيما يلي بعض المزايا الرئيسية لاستخدام عمليات التثبيت:

• إنشاء تثبيت أو تحديثه غير فعال بالكامل. حتى تتمكن من إعادة المحاولة دون أي مخاوف بشأن التسجيلات المكررة.
• يدعم نموذج التثبيت تنسيق علامة خاص ($InstallationId:{INSTALLATION_ID}) يتيح إرسال إعلام مباشرة إلى الجهاز المحدد. على سبيل المثال، إذا كانت التعليمات البرمجية للتطبيق تعيِّن معرف تثبيت joe93developer لهذا الجهاز المعين، يمكن للمطور استهداف هذا الجهاز عند إرسال إشعار إلى العلامة $InstallationId:{joe93developer}. يمكنك هذا من استهداف جهاز معين دون الحاجة إلى القيام بأي ترميز إضافي.
• يمكنك استخدام عمليات التثبيت أيضاً من إجراء تحديثات تسجيل جزئية. يتم طلب التحديث الجزئي للتثبيت باستخدام أسلوب PATCH باستخدام معيار JSON-Patch. يكون هذا مفيداً عندما تريد تحديث العلامات على التسجيل. ليس عليك سحب التسجيل بأكمله ثم إعادة إرسال جميع العلامات السابقة مرة أخرى.

يمكن أن يحتوي التثبيت على الخصائص التالية. للحصول على قائمة كاملة بخصائص التثبيت، راجع إنشاء تثبيت أو الكتابة فوقه باستخدام واجهة برمجة تطبيقات REST أو خصائص التثبيت.

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

ملاحظة

بشكل افتراضي، لا تنتهي صلاحية التسجيلات والتثبيتات.

يجب أن تحتوي التسجيلات والتثبيتات على مؤشر PNS صالح لكل جهاز/قناة. نظراً لأنه لا يمكن الحصول على مؤشرات PNS إلا في تطبيق عميل على الجهاز، فإن أحد الأنماط يتمثل في التسجيل مباشرة على هذا الجهاز باستخدام تطبيق العميل. من ناحية أخرى، قد تتطلب اعتبارات الأمان ومنطق العمل المتعلق بالعلامات إدارة تسجيل الجهاز في الواجهة الخلفية للتطبيق.

عند إجراء الدفع إلى مقبض انتهت صلاحيته بواسطة PNS، تقوم Azure Notification Hubs تلقائيا بتنظيف سجل التثبيت/التسجيل المرتبط استنادا إلى الاستجابة المستلمة من خادم PNS. لمسح السجلات منتهية الصلاحية من مركز إعلامات ثانوي، أضف منطقاً مخصصاً يعالج الملاحظات الواردة من كل عملية إرسال. ثم أضف عملية التثبيت/التسجيل منتهية الصلاحية في مركز الإعلامات الثانوي.

ملاحظة

لا تدعم واجهة برمجة تطبيقات التثبيتات خدمة Baidu (على الرغم من أن واجهة برمجة تطبيقات التسجيلات تدعمها).

القوالب

إذا كنت ترغب في استخدام القوالب، فإن تثبيت الجهاز يحتفظ أيضاً بجميع القوالب المقترنة بهذا الجهاز بتنسيق JSON (راجع النموذج أعلاه). تساعد أسماء القوالب في استهداف قوالب مختلفة لنفس الجهاز.

يتم تعيين كل اسم قالب إلى نص قالب ومجموعة اختيارية من العلامات. علاوة على ذلك، يمكن أن يكون لكل نظام أساسي خصائص قالب إضافية. بالنسبة إلى متجر Windows (باستخدام WNS)، يمكن أن تكون مجموعة إضافية من العناوين جزءا من القالب. في حالة APNs، يمكنك تعيين خاصية انتهاء الصلاحية إلى ثابت أو إلى تعبير قالب. للحصول على قائمة كاملة بخصائص التثبيت، راجع إنشاء تثبيت أو الكتابة فوقه باستخدام موضوع REST.

اللوحات الثانوية لتطبيقات متجر Windows

بالنسبة لتطبيقات عميل 'متجر Windows'، يكون إرسال الإعلامات إلى الإطارات المتجانبة الثانوية هو نفسه إرسالها إلى اللوحة الأساسية. هذا مدعوم أيضاً في عمليات التثبيت. تحتوي اللوحات الثانوية على ChannelUri مختلف، والذي تتعامل معه SDK على تطبيق العميل بشفافية.

يستخدم قاموس SecondaryTiles نفس TileId المستخدم لإنشاء كائن SecondaryTiles في تطبيق 'متجر Windows'. كما هو الحال مع ChannelUri الأساسي، يمكن تغيير ChannelUris من الإطارات المتجانبة الثانوية في أي لحظة. من أجل الاحتفاظ بالتثبيتات في مركز الإعلامات محدثة، يجب على الجهاز تحديثها باستخدام ChannelUris الحالي من الإطارات المتجانبة الثانوية.

إدارة التسجيل من الجهاز

عند إدارة تسجيل الجهاز من تطبيقات العميل، تكون الواجهة الخلفية مسؤولة فقط عن إرسال الإعلامات. تحافظ تطبيقات العميل على معالجة PNS محدثة، وتسجل العلامات. توضح الصورة التالية هذا النمط.

يسترد الجهاز أولاً مؤشر PNS من PNS، ثم يسجل مع مركز الإعلام مباشرة. بعد نجاح التسجيل، يمكن للواجهة الخلفية للتطبيق إرسال إشعار يستهدف هذا التسجيل. لمزيد من المعلومات حول كيفية إرسال الإعلامات، راجع التوجيه وتعبيرات العلامات.

في هذه الحالة، يمكنك استخدام حقوق الاستماع فقط للوصول إلى مراكز الإعلامات من الجهاز. لمزيد من المعلومات، راجع "الأمن".

يعد التسجيل من الجهاز أبسط طريقة، ولكن تشوبه بعض العيوب:

• يمكن لتطبيق العميل تحديث علاماته فقط عندما يكون التطبيق نشطاً. على سبيل المثال، إذا كان لدى المستخدم جهازان يسجلان العلامات المتعلقة بفرق الرياضة، عندما يسجل الجهاز الأول للحصول على علامة إضافية (على سبيل المثال، Seahawks)، فلن يتلقى الجهاز الثاني الإعلامات حول Seahawks حتى يتم تنفيذ التطبيق على الجهاز الثاني مرة ثانية. بشكل عام، عندما تتأثر العلامات بأجهزة متعددة، فإن إدارة العلامات من الواجهة الخلفية خيار مرغوب فيه.
• نظراً لأنه يمكن اختراق التطبيقات، فإن تأمين التسجيل إلى علامات معينة يتطلب عناية إضافية، كما هو موضح في المقالة الأمان.

مثال على التعليمات البرمجية للتسجيل مع مركز إعلام من جهاز باستخدام تثبيت

في هذا الوقت، يتم دعم هذا فقط باستخدام واجهة برمجة تطبيقات REST لمراكز الإعلامات.

يمكنك أيضاً استخدام أسلوب PATCH باستخدام معيار JSON-Patch لتحديث التثبيت.

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

مثال على التعليمات البرمجية للتسجيل مع مركز إعلام من جهاز باستخدام تسجيل

تنشئ هذه الطرق أو تحدث تسجيلاً للجهاز الذي يتم استدعاؤها عليه. وهذا يعني أنه من أجل تحديث المؤشر أو العلامات، يجب الكتابة فوق التسجيل بأكمله. تذكر أن التسجيلات عابرة، لذلك يجب أن يكون لديك دائماً مخزن موثوق به مع العلامات الحالية التي يحتاجها جهاز معين.

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

إدارة التسجيلات من الواجهة الخلفية

تتطلب إدارة التسجيلات من الواجهة الخلفية كتابة تعليمات برمجية إضافية. يجب أن يوفر التطبيق من الجهاز مؤشر PNS المحدث إلى الواجهة الخلفية في كل مرة يبدأ فيها التطبيق (جنباً إلى جنب مع العلامات والقوالب)، ويجب أن تقوم الواجهة الخلفية بتحديث هذا المؤشر على مركز الإعلامات. توضح الصورة التالية هذا التصميم.

تتضمن مزايا «إدارة التسجيلات» من الواجهة الخلفية القدرة على تعديل العلامات إلى التسجيلات حتى عندما يكون التطبيق المقابل على الجهاز غير نشط، ومصادقة تطبيق العميل قبل إضافة علامة إلى تسجيله.

مثال على التعليمات البرمجية للتسجيل مع مركز إعلامات من خلفية باستخدام تثبيت

لا يزال جهاز العميل يحصل على مؤشر PNS الخاص به وخصائص التثبيت ذات الصلة كما كان من قبل، ويستدعي واجهة برمجة تطبيقات مخصصة على الواجهة الخلفية التي يمكنها تنفيذ علامات التسجيل والتخويل وما إلى ذلك. يمكن للواجهة الخلفية الاستفادة من Notification Hub SDK لعمليات الواجهة الخلفية.

يمكنك أيضاً استخدام أسلوب PATCH باستخدام معيار JSON-Patch لتحديث التثبيت.

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

مثال على التعليمات البرمجية للتسجيل مع مركز إعلام من خلفية باستخدام معرف تسجيل

من خلفية التطبيق، يمكنك تنفيذ عمليات CRUDS الأساسية على التسجيلات. على سبيل المثال:

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

يجب أن تتعامل الواجهة الخلفية مع التزامن بين تحديثات التسجيل. يوفر ناقل خدمة Microsoft Azure تحكماً متفائلاً في التزامن لإدارة التسجيل. على مستوى HTTP، يتم تنفيذ هذا باستخدام ETag في عمليات إدارة التسجيل. يتم استخدام هذه الميزة بشفافية من قبل Microsoft SDKs، والتي تطرح استثناءً إذا تم رفض تحديث لأسباب تتعلق بالتزامن. الواجهة الخلفية للتطبيق مسؤولة عن معالجة هذه الاستثناءات وإعادة محاولة التحديث إذا لزم الأمر.