注册管理

项目
09/08/2023

本主题说明如何向通知中心注册设备以接收推送通知。本主题将概要介绍注册，并介绍注册设备的两种主要模式：直接从设备向通知中心注册，以及通过应用程序后端注册。

什么是设备注册

向通知中心注册设备是通过使用“注册”或“安装”来完成的。

注册

注册将设备的平台通知服务 (PNS) 句柄与标记（有时还包括模板）相关联。 PNS 句柄可以是 ChannelURI 或设备令牌注册 ID。标记用于将通知路由到一组正确的设备句柄。有关详细信息，请参阅路由和标记表达式。模板用于实现按注册转换。有关详细信息，请参阅模板。

注意

Azure 通知中心支持每个设备注册最多 60 个标记。

安装

安装是增强型的注册，包含推送相关的属性包。这是使用服务器端 .NET SDK（用于后端操作的通知中心 SDK）注册设备的最新且最佳方法。还可使用通知中心 REST API 方法在客户端设备自身上注册安装。如果使用后端服务，则应能够使用用于后端操作的通知中心 SDK。

以下是使用安装的一些主要优点：

创建或更新安装是完全幂等的。因此可以重试该操作，而不需要顾虑重复注册的情况。
此安装模型支持特殊的标记格式 ($InstallationId:{INSTALLATION_ID})，该格式允许将通知直接发送到特定的设备。例如，如果应用的代码为此特定设备设置了安装 ID joe93developer，则开发人员在向 $InstallationId:{joe93developer} 标记发送通知时，可以将此设备作为目标。这样，无需编写任何额外的代码，就能将特定设备作为目标。
使用安装还能执行部分注册更新。可以使用 JSON-Patch standard以 PATCH 方法来请求部分安装更新。想要更新注册中的标记时，此方法很有用。用户不需要删除整个注册，并重新发送前面的所有标记。

安装可包含以下属性。有关完整的安装属性列表，请参阅使用 REST API 创建或覆盖安装或安装属性。

// 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 通知中心会根据从 PNS 服务器接收到的响应自动清除关联的安装/注册记录。若要从辅助通知中心清理过期的记录，请添加自定义逻辑来处理每次发送的反馈。然后，使辅助通知中心中的安装/注册过期。

注意

安装 API 不支持百度服务（尽管注册 API 支持）。

模板

如果要使用模板，则设备安装还会保存与设备关联的、采用 JSON 格式的所有模板（请参阅上面的示例）。模板名称有助于将目标指向相同设备的不同模板。

每个模板名称会映射到一个模板主体和一组可选标记。此外，每个平台可能有附加的模板属性。对于 Windows 应用商店（使用 WNS），模板中还可能会有一组附加标头。对于 APNs，可以将过期属性设为常量或模板表达式。有关完整的安装属性列表，请参阅使用 REST 创建或覆盖安装主题。

Windows 应用商店应用的辅助磁贴

对于 Windows 应用商店客户端应用程序，将通知发送到辅助磁贴与将通知发送到主磁贴相同。安装中也支持此行为。辅助磁贴具有不同的 ChannelUri，客户端应用上的 SDK 会以透明方式处理此 ChannelUri。

SecondaryTiles 字典使用的 TileId 与在 Windows 应用商店应用中创建 SecondaryTiles 时使用的 TileId 相同。与主 ChannelUri 一样，辅助磁贴的 ChannelUri 可随时更改。为了使通知中心中的安装保持更新，设备必须使用辅助磁贴的当前 ChannelUri 刷新这些安装。

从设备管理注册

从客户端应用管理设备注册时，后端只负责发送通知。客户端应用使 PNS 句柄保持最新状态，并且会注册标记。下图演示了此模式。

Registration from device

设备首先从 PNS 检索 PNS 句柄，然后直接向通知中心进行注册。注册成功之后，应用后端即可发送以该注册为目标的通知。有关如何发送通知的详细信息，请参阅路由和标记表达式。

在此情况下，只可使用“侦听”权限从设备访问通知中心。有关详细信息，请参阅安全性。

从设备注册是最简单的方法，但存在一些缺点：

客户端应用只能在它处于活动状态时更新其标记。例如，如果用户有两台设备要注册与体育团队相关的标记，则当第一台设备注册附加标记（例如，Seahawks）时，第二台设备将不会收到有关 Seahawks 的通知，直到第二次在第二台设备上执行应用程序为止。更概括地说，如果标记受多个设备的影响，则从后端管理标记是理想的选择。
由于应用可能会受到黑客攻击，因此保护特定标记的注册需要格外小心，如安全性一文中所述。

使用安装从设备向通知中心注册的示例代码

此时，仅支持使用通知中心 REST API执行此操作。

也可以使用 JSON-Patch standard 以 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 句柄（以及标记和模板），然后后端必须在通知中心上更新此句柄。下图演示了此设计。

Registration management

从后端管理注册的优点是即使在设备上的相应应用处于非活动状态也能修改注册标记，并且在向其注册添加标记之前能够对客户端应用进行身份验证。

使用安装从后端向通知中心注册的示例代码

客户端设备仍会像前面一样获取其 PNS 句柄及相关的安装属性，然后在可以执行注册和授权标记等的后端上调用自定义 API。后端可以利用适用于后端操作的通知中心 SDK。