Como usar Hubs de Notificação a partir de Java

Este tópico descreve os principais recursos do novo SDK Java oficial do Hub de Notificação do Azure totalmente suportado. Este projeto é um projeto de código aberto e você pode visualizar todo o código do SDK no Java SDK.

Em geral, você pode acessar todos os recursos dos Hubs de Notificação a partir de um back-end Java/PHP/Python/Ruby usando a interface REST do Hub de Notificação, conforme descrito no tópico do MSDN APIs REST dos Hubs de Notificação. Este Java SDK fornece um wrapper fino sobre essas interfaces REST em Java.

Atualmente, o SDK suporta:

• CRUD nos Hubs de Notificação
• CRUD sobre Inscrições
• Gestão de Instalação
• Registos de Importação/Exportação
• Envios regulares
• Envios agendados
• Operações assíncronas via 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)

Uso do SDK

Compilar e construir

Use Maven

Para construir:

mvn package

Código

CRUDs do Hub de Notificações

Crie 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 Hub de Notificação:

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

Excluir Hub de Notificação:

namespaceManager.deleteNotificationHub("hubname");

CRUDs de Registo

Crie um cliente do Hub de Notificação:

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

Criar registro 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, você pode criar registros para Android (FCM), Windows Phone (MPNS) e Kindle Fire (ADM).

Crie registros de modelo:

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

Crie registros usando o padrão create registration ID + upsert:

Remove duplicados devido a quaisquer respostas perdidas ao armazenar IDs de registro 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 inscrição única:

hub.getRegistration(regid);

• Obtenha todos os registos no hub:

hub.getRegistrations();

• Obtenha inscrições com a tag:

hub.getRegistrationsByTag("myTag");

• Obtenha inscrições por canal:

hub.getRegistrationsByChannel("devicetoken");

Todas os pedidos de coleção suportam $top e tokens de continuação.

Uso da API de instalação

A API de instalação é um mecanismo alternativo para o gerenciamento de registros. Em vez de manter vários registros, que não são triviais e podem ser facilmente feitos de forma incorreta ou ineficiente, agora é possível usar um objeto SINGLE Installation.

A instalação contém tudo o que você precisa: canal push (token de dispositivo), tags, modelos, blocos secundários (para WNS e APNS). Você não precisa mais ligar para o serviço para obter ID - basta gerar GUID ou qualquer outro identificador, mantê-lo no dispositivo e enviar para o seu back-end junto com o canal push (token do dispositivo).

No back-end, você deve fazer apenas uma única chamada para CreateOrUpdateInstallation: é totalmente idempotente, então sinta-se livre para tentar novamente, se necessário.

Como exemplo para o Amazon Kindle Fire:

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

Se você quiser 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, use o recurso de atualização parcial, que permite modificar apenas propriedades específicas do objeto de instalação. Atualização parcial é um subconjunto de operações de patch JSON que você pode executar no objeto Installation.

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

Excluir instalação:

hub.deleteInstallation(installation.getInstallationId());

CreateOrUpdate, Patche Delete são eventualmente consistentes com Get. Sua operação solicitada apenas vai para a fila do sistema durante a chamada e é executada em segundo plano. O Get não foi projetado para o cenário principal de tempo de execução, mas apenas para fins de depuração e solução de problemas, ele é fortemente limitado pelo serviço.

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

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

Para um dos 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 nível STANDARD)

O mesmo que o envio regular, 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.

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

Importação/Exportação (disponível para o nível STANDARD)

Talvez seja necessário executar uma operação em massa contra registros. Geralmente é para integração com outro sistema ou uma correção massiva para atualizar as tags. Não recomendamos o uso do fluxo Get/Update se milhares de registros estiverem envolvidos. A capacidade de Importação/Exportação do sistema foi projetada para cobrir o cenário. Você fornecerá acesso a um contêiner de blob em sua conta de armazenamento como uma fonte de dados de entrada e local para saída.

Enviar um trabalho de exportação:

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

Enviar um trabalho 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;
}

Obtenha todos os empregos:

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

URI com assinatura SAS:

Este URL é o URL de um arquivo de blob ou contêiner de blob mais um conjunto de parâmetros como permissões e tempo de expiração mais assinatura de todas essas coisas feitas usando a chave SAS da conta. O SDK Java do Armazenamento do Azure tem recursos avançados, incluindo a criação desses URIs. Como alternativa simples, dê uma olhada na classe de teste ImportExportE2E (do local do GitHub) que tem uma implementação básica e compacta do algoritmo de assinatura.

Enviar notificações

O objeto Notification é simplesmente um corpo com cabeçalhos, alguns métodos de utilidade ajudam na criação dos objetos de notificações nativos e de modelo.

• Windows Store 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);

• Kindle Fire

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

• Enviar para Tags

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

• Enviar para expressão de tag

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 seu código Java deve agora produzir uma notificação que aparece no seu dispositivo de destino.

Próximos passos

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

• Faça o download do Java SDK completo, que contém todo o código do SDK.
• Brinque com as amostras:
  • Introdução aos Hubs de Notificação
  • Enviar últimas notícias
  • Envie notícias de última hora localizadas
  • Enviar notificações para usuários autenticados
  • Enviar notificações entre plataformas para usuários autenticados