Gestão de registosRegistration management

Descrição geralOverview

Este tópico explica como registrar dispositivos com hubs de notificação para receber notificações por push.This topic explains how to register devices with notification hubs in order to receive push notifications. O tópico descreve os registros em um alto nível e, em seguida, apresenta os dois padrões principais para o registro de dispositivos: registro do dispositivo diretamente no Hub de notificação e registro por meio de um back-end do aplicativo.The topic describes registrations at a high level, then introduces the two main patterns for registering devices: registering from the device directly to the notification hub, and registering through an application backend.

O que é registro de dispositivoWhat is device registration

O registro de dispositivo com um hub de notificação é realizado usando um registro ou uma instalação.Device registration with a Notification Hub is accomplished using a Registration or Installation.

RegistosRegistrations

Um registro associa o identificador PNS (serviço de notificação de plataforma) para um dispositivo com marcas e possivelmente um modelo.A registration associates the Platform Notification Service (PNS) handle for a device with tags and possibly a template. O identificador PNS pode ser um ChannelURI, um token de dispositivo ou uma ID de registro FCM. As marcas são usadas para rotear notificações para o conjunto correto de identificadores de dispositivo.The PNS handle could be a ChannelURI, device token, or FCM registration id. Tags are used to route notifications to the correct set of device handles. Para obter mais informações, consulte expressões de marca e de roteamento.For more information, see Routing and Tag Expressions. Os modelos são usados para implementar a transformação por registro.Templates are used to implement per-registration transformation. Para obter mais informações, veja Templates (Modelos).For more information, see Templates.

Nota

Os hubs de notificação do Azure dão suporte a um máximo de 60 marcas por dispositivo.Azure Notification Hubs supports a maximum of 60 tags per device.

PermanecerInstallations

Uma instalação é um registro aprimorado que inclui uma bolsa de propriedades relacionadas ao Push.An Installation is an enhanced registration that includes a bag of push related properties. Trata-se da abordagem mais recente e melhor para registrar seus dispositivos.It is the latest and best approach to registering your devices. No entanto, ele não tem suporte do SDK do .NET do lado do cliente (SDK do hub de notificação para operações de back-end) a partir de ainda.However, it is not supported by client-side .NET SDK (Notification Hub SDK for backend operations) as of yet. Isso significa que se você estiver registrando a partir do próprio dispositivo cliente, precisaria usar a abordagem da API REST dos hubs de notificação para dar suporte a instalações.This means if you are registering from the client device itself, you would have to use the Notification Hubs REST API approach to support installations. Se você estiver usando um serviço de back-end, deverá ser capaz de usar o SDK do hub de notificação para operações de back-end.If you are using a backend service, you should be able to use Notification Hub SDK for backend operations.

A seguir estão algumas das principais vantagens para o uso de instalações do:The following are some key advantages to using installations:

  • Criar ou atualizar uma instalação é totalmente idempotente.Creating or updating an installation is fully idempotent. Portanto, você pode tentar novamente sem qualquer preocupação sobre registros duplicados.So you can retry it without any concerns about duplicate registrations.
  • O modelo de instalação do oferece suporte a um$InstallationId:{INSTALLATION_ID}formato de marca especial () que permite enviar uma notificação diretamente para o dispositivo específico.The installation model supports a special tag format ($InstallationId:{INSTALLATION_ID}) that enables sending a notification directly to the specific device. Por exemplo, se o código do aplicativo definir uma ID de joe93developer instalação para esse dispositivo específico, um desenvolvedor poderá direcionar esse dispositivo ao enviar uma notificação para a $InstallationId:{joe93developer} marca.For example, if the app's code sets an installation ID of joe93developer for this particular device, a developer can target this device when sending a notification to the $InstallationId:{joe93developer} tag. Isso permite que você direcione um dispositivo específico sem precisar fazer nenhuma codificação adicional.This enables you to target a specific device without having to do any additional coding.
  • O uso de instalações também permite que você faça atualizações parciais de registro.Using installations also enables you to do partial registration updates. A atualização parcial de uma instalação é solicitada com um método de PATCH usando o padrão JSON-patch.The partial update of an installation is requested with a PATCH method using the JSON-Patch standard. Isso é útil quando você deseja atualizar as marcas no registro.This is useful when you want to update tags on the registration. Você não precisa retirar todo o registro e reenviar todas as marcas anteriores novamente.You don't have to pull down the entire registration and then resend all the previous tags again.

Uma instalação pode conter as propriedades a seguir.An installation can contain the following properties. Para obter uma lista completa das propriedades de instalação, consulte criar ou substituir uma instalação com a API REST ou as propriedades de instalação.For a complete listing of the installation properties, see Create or Overwrite an Installation with REST API or Installation Properties.

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

Nota

Por padrão, os registros e as instalações não expiram.By default, registrations and installations do not expire.

Os registros e as instalações devem conter um identificador PNS válido para cada dispositivo/canal.Registrations and installations must contain a valid PNS handle for each device/channel. Como os identificadores de PNS só podem ser obtidos em um aplicativo cliente no dispositivo, um padrão é registrar-se diretamente no dispositivo com o aplicativo cliente.Because PNS handles can only be obtained in a client app on the device, one pattern is to register directly on that device with the client app. Por outro lado, as considerações de segurança e a lógica de negócios relacionadas a marcas podem exigir que você gerencie o registro de dispositivos no back-end do aplicativo.On the other hand, security considerations and business logic related to tags might require you to manage device registration in the app back-end.

Nota

A API de instalações não oferece suporte ao serviço Baidu (embora a API de registros faça isso).The Installations API does not support the Baidu service (although the Registrations API does).

ModelosTemplates

Se você quiser usar modelos, a instalação do dispositivo também manterá todos os modelos associados a esse dispositivo em um formato JSON (consulte o exemplo acima).If you want to use Templates, the device installation also holds all templates associated with that device in a JSON format (see sample above). Os nomes de modelo ajudam a direcionar modelos diferentes para o mesmo dispositivo.The template names help target different templates for the same device.

Cada nome de modelo é mapeado para um corpo de modelo e um conjunto opcional de marcas.Each template name maps to a template body and an optional set of tags. Além disso, cada plataforma pode ter propriedades de modelo adicionais.Moreover, each platform can have additional template properties. Para a Windows Store (usando WNS) e o Windows Phone 8 (usando MPNS), um conjunto adicional de cabeçalhos pode fazer parte do modelo.For Windows Store (using WNS) and Windows Phone 8 (using MPNS), an additional set of headers can be part of the template. No caso do APNs, você pode definir uma propriedade de expiração como uma constante ou uma expressão de modelo.In the case of APNs, you can set an expiry property to either a constant or to a template expression. Para obter uma lista completa das propriedades de instalação, consulte criar ou substituir um tópico de instalação com REST .For a complete listing of the installation properties see, Create or Overwrite an Installation with REST topic.

Blocos secundários para aplicativos da Windows StoreSecondary Tiles for Windows Store Apps

Para aplicativos cliente da Windows Store, o envio de notificações para blocos secundários é o mesmo que enviá-los para o primário.For Windows Store client applications, sending notifications to secondary tiles is the same as sending them to the primary one. Isso também é suportado em instalações do.This is also supported in installations. Os blocos secundários têm um ChannelUri diferente, que o SDK em seu aplicativo cliente manipula de forma transparente.Secondary tiles have a different ChannelUri, which the SDK on your client app handles transparently.

O dicionário SecondaryTiles usa o mesmo Tileid usado para criar o objeto SecondaryTiles em seu aplicativo da Windows Store.The SecondaryTiles dictionary uses the same TileId that is used to create the SecondaryTiles object in your Windows Store app. Assim como acontece com o ChannelUri primário, os ChannelUris de blocos secundários podem mudar a qualquer momento.As with the primary ChannelUri, ChannelUris of secondary tiles can change at any moment. Para manter as instalações no Hub de notificação atualizadas, o dispositivo deve atualizá-las com a ChannelUris atual dos blocos secundários.In order to keep the installations in the notification hub updated, the device must refresh them with the current ChannelUris of the secondary tiles.

Gerenciamento de registro do dispositivoRegistration management from the device

Ao gerenciar o registro de dispositivos de aplicativos cliente, o back-end é responsável somente pelo envio de notificações.When managing device registration from client apps, the backend is only responsible for sending notifications. Os aplicativos cliente mantêm PNS identificadores atualizados e registram as marcas.Client apps keep PNS handles up-to-date, and register tags. A figura a seguir ilustra esse padrão.The following picture illustrates this pattern.

O dispositivo primeiro recupera o identificador PNS do PNS e, em seguida, registra-se diretamente no Hub de notificação.The device first retrieves the PNS handle from the PNS, then registers with the notification hub directly. Depois que o registro for bem-sucedido, o back-end do aplicativo poderá enviar uma notificação direcionando esse registro.After the registration is successful, the app backend can send a notification targeting that registration. Para obter mais informações sobre como enviar notificações, consulte expressões de marca e de roteamento.For more information about how to send notifications, see Routing and Tag Expressions.

Nesse caso, você usa apenas os direitos de escuta para acessar os hubs de notificação do dispositivo.In this case, you use only Listen rights to access your notification hubs from the device. Para obter mais informações, consulte segurança.For more information, see Security.

O registro do dispositivo é o método mais simples, mas tem algumas desvantagens:Registering from the device is the simplest method, but it has some drawbacks:

  • Um aplicativo cliente só pode atualizar suas marcas quando o aplicativo está ativo.A client app can only update its tags when the app is active. Por exemplo, se um usuário tiver dois dispositivos que registram marcas relacionadas às equipes de esporte, quando o primeiro dispositivo se registra para uma marca adicional (por exemplo, Seahawks), o segundo dispositivo não receberá as notificações sobre o Seahawks até que o aplicativo no segundo dispositivo seja executado uma segunda vez.For example, if a user has two devices that register tags related to sport teams, when the first device registers for an additional tag (for example, Seahawks), the second device will not receive the notifications about the Seahawks until the app on the second device is executed a second time. Em geral, quando as marcas são afetadas por vários dispositivos, o gerenciamento de marcas do back-end é uma opção desejável.More generally, when tags are affected by multiple devices, managing tags from the backend is a desirable option.
  • Como os aplicativos podem ser invadidos, proteger o registro para marcas específicas requer cuidado extra, conforme explicado na seção "segurança em nível de marca".Since apps can be hacked, securing the registration to specific tags requires extra care, as explained in the section “Tag-level security.”

Exemplo de código para registrar com um hub de notificação de um dispositivo usando uma instalaçãoExample code to register with a notification hub from a device using an installation

Neste momento, só há suporte para isso usando a API REST dos hubs de notificação.At this time, this is only supported using the Notification Hubs REST API.

Você também pode usar o método PATCH usando o padrão JSON-patch para atualizar a instalação.You can also use the PATCH method using the JSON-Patch standard for updating the installation.

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

Exemplo de código para registrar com um hub de notificação de um dispositivo usando um registroExample code to register with a notification hub from a device using a registration

Esses métodos criam ou atualizam um registro para o dispositivo no qual eles são chamados.These methods create or update a registration for the device on which they are called. Isso significa que, para atualizar o identificador ou as marcas, você deve substituir todo o registro.This means that in order to update the handle or the tags, you must overwrite the entire registration. Lembre-se de que os registros são transitórios, portanto, você deve sempre ter um armazenamento confiável com as marcas atuais de que um dispositivo específico precisa.Remember that registrations are transient, so you should always have a reliable store with the current tags that a specific device needs.

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

Gerenciamento de registro de um back-endRegistration management from a backend

O gerenciamento de registros do back-end requer a escrita de código adicional.Managing registrations from the backend requires writing additional code. O aplicativo do dispositivo deve fornecer o identificador PNS atualizado para o back-end sempre que o aplicativo é iniciado (juntamente com marcas e modelos) e o back-end deve atualizar esse identificador no Hub de notificação.The app from the device must provide the updated PNS handle to the backend every time the app starts (along with tags and templates), and the backend must update this handle on the notification hub. A figura a seguir ilustra esse design.The following picture illustrates this design.

As vantagens de gerenciar os registros do back-end incluem a capacidade de modificar marcas para registros, mesmo quando o aplicativo correspondente no dispositivo está inativo e para autenticar o aplicativo cliente antes de adicionar uma marca ao seu registro.The advantages of managing registrations from the backend include the ability to modify tags to registrations even when the corresponding app on the device is inactive, and to authenticate the client app before adding a tag to its registration.

Exemplo de código para registrar com um hub de notificação de um back-end usando uma instalaçãoExample code to register with a notification hub from a backend using an installation

O dispositivo cliente ainda obtém seu identificador PNS e as propriedades de instalação relevantes como antes e chama uma API personalizada no back-end que pode executar o registro e autorizar as marcas etc. O back-end pode aproveitar o SDK do hub de notificação para operações de back-end.The client device still gets its PNS handle and relevant installation properties as before and calls a custom API on the backend that can perform the registration and authorize tags etc. The backend can leverage the Notification Hub SDK for backend operations.

Você também pode usar o método PATCH usando o padrão JSON-patch para atualizar a instalação.You can also use the PATCH method using the JSON-Patch standard for updating the installation.

// 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 "mpns":
            installation.Platform = NotificationPlatform.Mpns;
            break;
        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);
}

Exemplo de código para registrar com um hub de notificação de um dispositivo usando uma ID de registroExample code to register with a notification hub from a device using a registration ID

No back-end do aplicativo, você pode executar operações CRUD básicas em registros.From your app backend, you can perform basic CRUDS operations on registrations. Por exemplo:For example:

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

O back-end deve lidar com a simultaneidade entre atualizações de registro.The backend must handle concurrency between registration updates. O barramento de serviço oferece controle de simultaneidade otimista para gerenciamento de registro.Service Bus offers optimistic concurrency control for registration management. No nível de HTTP, isso é implementado com o uso de ETag nas operações de gerenciamento de registro.At the HTTP level, this is implemented with the use of ETag on registration management operations. Esse recurso é usado de forma transparente pelos SDKs da Microsoft, que geram uma exceção se uma atualização é rejeitada por motivos de simultaneidade.This feature is transparently used by Microsoft SDKs, which throw an exception if an update is rejected for concurrency reasons. O back-end do aplicativo é responsável por lidar com essas exceções e repetir a atualização, se necessário.The app backend is responsible for handling these exceptions and retrying the update if necessary.