Como utilizar Hubs de Notificação de Java

Este tópico descreve as principais funcionalidades do novo SDK Java do Hub de Notificação do Azure totalmente suportado. Este projeto é um projeto open source e pode ver todo o código SDK no SDK Java.

Em geral, pode aceder a todas as funcionalidades dos Notification Hubs a partir de um back-end Java/PHP/Python/Ruby com a interface REST do Hub de Notificação, conforme descrito no tópico MSDN Notification Hubs REST APIs. Este SDK Java fornece um wrapper fino sobre estas interfaces REST em Java.

O SDK suporta atualmente:

• CRUD nos Hubs de Notificação
• CRUD em Registos
• Gestão de Instalações
• Importar/Exportar Registos
• Envios Regulares
• Envios Agendados
• Operações assíncronas através do Java NIO
• Plataformas suportadas: APNS (iOS), FCM (Android), WNS (aplicações da Loja Windows), MPNS(Windows Phone), ADM (Amazon Kindle Fire), Baidu (Android sem serviços Google)

Utilização do SDK

Compilar e compilar

Utilizar o Maven

Para compilar:

mvn package

Código

CRUDs do Hub de Notificação

Criar um NamespaceManager:

NamespaceManager namespaceManager = new NamespaceManager("connection string")

Criar Hub de Notificação:

NotificationHubDescription hub = new NotificationHubDescription("hubname");
hub.setWindowsCredential(new WindowsCredential("sid","key"));
hub = namespaceManager.createNotificationHub(hub);

OU

hub = new NotificationHub("connection string", "hubname");

Obter Hub de Notificação:

hub = namespaceManager.getNotificationHub("hubname");

Atualizar o Hub de Notificação:

hub.setMpnsCredential(new MpnsCredential("mpnscert", "mpnskey"));
hub = namespaceManager.updateNotificationHub(hub);

Eliminar Hub de Notificação:

namespaceManager.deleteNotificationHub("hubname");

CRUDs de Registo

Criar um cliente do Notification Hub:

hub = new NotificationHub("connection string", "hubname");

Criar registo do Windows:

WindowsRegistration reg = new WindowsRegistration(new URI(CHANNELURI));
reg.getTags().add("myTag");
reg.getTags().add("myOtherTag");
hub.createRegistration(reg);

Criar registo iOS:

AppleRegistration reg = new AppleRegistration(DEVICETOKEN);
reg.getTags().add("myTag");
reg.getTags().add("myOtherTag");
hub.createRegistration(reg);

Da mesma forma, pode criar registos para Android (FCM), Windows Phone (MPNS) e Kindle Fire (ADM).

Criar registos de modelos:

WindowsTemplateRegistration reg = new WindowsTemplateRegistration(new URI(CHANNELURI), WNSBODYTEMPLATE);
reg.getHeaders().put("X-WNS-Type", "wns/toast");
hub.createRegistration(reg);

Crie registos com o padrão criar ID de registo + upsert:

Remove duplicados devido a quaisquer respostas perdidas se armazenar IDs de registo no dispositivo:

String id = hub.createRegistrationId();
WindowsRegistration reg = new WindowsRegistration(id, new URI(CHANNELURI));
hub.upsertRegistration(reg);

Atualizar registos:

hub.updateRegistration(reg);

Eliminar registos:

hub.deleteRegistration(regid);

Registos de consultas:

• Obter registo único:

hub.getRegistration(regid);

• Obtenha todos os registos no hub:

hub.getRegistrations();

• Obter registos com etiqueta:

hub.getRegistrationsByTag("myTag");

• Obter registos por canal:

hub.getRegistrationsByChannel("devicetoken");

Todas as consultas de coleção suportam tokens de $top e continuação.

Utilização da API de Instalação

A API de instalação é um mecanismo alternativo para a gestão de registos. Em vez de manter múltiplos registos, que não são triviais e podem ser facilmente feitos de forma incorreta ou ineficaz, agora é possível utilizar um objeto de Instalação ÚNICA.

A instalação contém tudo o que precisa: canal push (token de dispositivo), etiquetas, modelos, mosaicos secundários (para WNS e APNS). Já não precisa de ligar para o serviço para obter o ID - apenas gerar GUID ou qualquer outro identificador, mantê-lo no dispositivo e enviar para o seu back-end juntamente com o canal push (token de dispositivo).

No back-end, só deve efetuar uma única chamada para CreateOrUpdateInstallation; é totalmente idempotente, pelo que pode tentar novamente, se necessário.

Como exemplo para Amazon Kindle Fire:

Installation installation = new Installation("installation-id", NotificationPlatform.Adm, "adm-push-channel");
hub.createOrUpdateInstallation(installation);

Se pretender atualizá-lo:

installation.addTag("foo");
installation.addTemplate("template1", new InstallationTemplate("{\"data\":{\"key1\":\"$(value1)\"}}","tag-for-template1"));
installation.addTemplate("template2", new InstallationTemplate("{\"data\":{\"key2\":\"$(value2)\"}}","tag-for-template2"));
hub.createOrUpdateInstallation(installation);

Para cenários avançados, utilize a capacidade de atualização parcial, que permite modificar apenas propriedades específicas do objeto de instalação. A atualização parcial é o subconjunto das operações de Patch JSON que pode executar no objeto instalação.

PartialUpdateOperation addChannel = new PartialUpdateOperation(UpdateOperationType.Add, "/pushChannel", "adm-push-channel2");
PartialUpdateOperation addTag = new PartialUpdateOperation(UpdateOperationType.Add, "/tags", "bar");
PartialUpdateOperation replaceTemplate = new PartialUpdateOperation(UpdateOperationType.Replace, "/templates/template1", new InstallationTemplate("{\"data\":{\"key3\":\"$(value3)\"}}","tag-for-template1")).toJson());
hub.patchInstallation("installation-id", addChannel, addTag, replaceTemplate);

Eliminar Instalação:

hub.deleteInstallation(installation.getInstallationId());

CreateOrUpdate, Patche Delete são eventualmente consistentes com Get. A operação pedida vai apenas para a fila do sistema durante a chamada e é executada em segundo plano. O Get não foi concebido para o cenário de runtime principal, mas apenas para fins de depuração e resolução de problemas, é fortemente limitado pelo serviço.

O fluxo de envio para Instalações é o mesmo que para Registos. Para direcionar a notificação para a Instalação específica , basta utilizar a etiqueta "InstallationId:{desired-id}". Neste caso, o código é:

Notification n = Notification.createWindowsNotification("WNS body");
hub.sendNotification(n, "InstallationId:{installation-id}");

Para um de vários modelos:

Map<String, String> prop =  new HashMap<String, String>();
prop.put("value3", "some value");
Notification n = Notification.createTemplateNotification(prop);
hub.sendNotification(n, "InstallationId:{installation-id} && tag-for-template1");

Agendar Notificações (disponível para o Escalão STANDARD)

O mesmo que o envio normal, mas com um parâmetro adicional - scheduledTime, que diz quando a notificação deve ser entregue. O serviço aceita qualquer ponto de tempo entre agora + 5 minutos e agora + 7 dias.

Agendar uma notificação nativa do Windows:

Calendar c = Calendar.getInstance();
c.add(Calendar.DATE, 1);
Notification n = Notification.createWindowsNotification("WNS body");
hub.scheduleNotification(n, c.getTime());

Importar/Exportar (disponível para o Escalão STANDARD)

Poderá ter de efetuar uma operação em massa em relação aos registos. Normalmente, destina-se à integração com outro sistema ou a uma correção massiva para atualizar as etiquetas. Não recomendamos a utilização do fluxo Get/Update se estiverem envolvidos milhares de registos. A capacidade de Importação/Exportação do sistema foi concebida para abranger o cenário. Irá fornecer acesso a um contentor de blobs na sua conta de armazenamento como uma origem de dados recebidos e localização para saída.

Submeter uma tarefa de exportação:

NotificationHubJob job = new NotificationHubJob();
job.setJobType(NotificationHubJobType.ExportRegistrations);
job.setOutputContainerUri("container uri with SAS signature");
job = hub.submitNotificationHubJob(job);

Submeter uma tarefa de importação:

NotificationHubJob job = new NotificationHubJob();
job.setJobType(NotificationHubJobType.ImportCreateRegistrations);
job.setImportFileUri("input file uri with SAS signature");
job.setOutputContainerUri("container uri with SAS signature");
job = hub.submitNotificationHubJob(job);

Aguarde até que um trabalho seja concluído:

while(true){
    Thread.sleep(1000);
    job = hub.getNotificationHubJob(job.getJobId());
    if(job.getJobStatus() == NotificationHubJobStatus.Completed)
        break;
}

Obter todas as tarefas:

List<NotificationHubJob> jobs = hub.getAllNotificationHubJobs();

URI com assinatura SAS:

Este URL é o URL de um ficheiro de blobs ou contentor de blobs, além de um conjunto de parâmetros, como permissões e tempo de expiração, além da assinatura de todos estes elementos efetuados com a chave SAS da conta. O SDK Java do Armazenamento do Azure tem capacidades avançadas, incluindo a criação destes URIs. Como alternativa simples, veja a ImportExportE2E classe de teste (a partir da localização do GitHub) que tem a implementação básica e compacta do algoritmo de assinatura.

Enviar Notificações

O objeto Notificação é simplesmente um corpo com cabeçalhos, alguns métodos utilitários ajudam a criar objetos de notificações nativas e de modelos.

• Loja Windows e Windows Phone 8.1 (não Silverlight)

String toast = "<toast><visual><binding template=\"ToastText01\"><text id=\"1\">Hello from Java!</text></binding></visual></toast>";
Notification n = Notification.createWindowsNotification(toast);
hub.sendNotification(n);

• iOS

String alert = "{\"aps\":{\"alert\":\"Hello from Java!\"}}";
Notification n = Notification.createAppleNotification(alert);
hub.sendNotification(n);

• Android

String message = "{\"data\":{\"msg\":\"Hello from Java!\"}}";
Notification n = Notification.createFcmNotification(message);
hub.sendNotification(n);

• Windows Phone 8.0 e 8.1 Silverlight

String toast = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
            "<wp:Notification xmlns:wp=\"WPNotification\">" +
                "<wp:Toast>" +
                    "<wp:Text1>Hello from Java!</wp:Text1>" +
                "</wp:Toast> " +
            "</wp:Notification>";
Notification n = Notification.createMpnsNotification(toast);
hub.sendNotification(n);

• Fogo kindle

String message = "{\"data\":{\"msg\":\"Hello from Java!\"}}";
Notification n = Notification.createAdmNotification(message);
hub.sendNotification(n);

• Enviar para Etiquetas

Set<String> tags = new HashSet<String>();
tags.add("boo");
tags.add("foo");
hub.sendNotification(n, tags);

• Enviar para expressão de etiqueta

hub.sendNotification(n, "foo && ! bar");

• Enviar notificação de modelo

Map<String, String> prop =  new HashMap<String, String>();
prop.put("prop1", "v1");
prop.put("prop2", "v2");
Notification n = Notification.createTemplateNotification(prop);
hub.sendNotification(n);

A execução do código Java deverá agora produzir uma notificação apresentada no seu dispositivo de destino.

Passos Seguintes

Este tópico mostrou-lhe como criar um cliente REST Java simples para Hubs de Notificação. A partir daqui, pode:

• Transfira o SDK Java completo, que contém todo o código SDK.
• Reproduzir com os exemplos:
  • Introdução aos Hubs de Notificação
  • Enviar notícias de última hora
  • Enviar notícias de última hora localizadas
  • Enviar notificações a utilizadores autenticados
  • Enviar notificações entre plataformas para utilizadores autenticados