Come usare Hub di notifica da JavaHow to use Notification Hubs from Java

Questo argomento descrive le funzionalità principali del nuovo ufficiale SDK per Java di Hub di notifica di Azure, completamente supportato.This topic describes the key features of the new fully supported official Azure Notification Hub Java SDK. Si tratta di un progetto open source ed è possibile visualizzare il codice SDK completo nell'articolo relativo all' SDK per Java.This is an open source project and you can view the entire SDK code at [Java SDK].

In generale, è possibile accedere a tutte le funzionalità di Hub di notifica da un back-end Java/PHP/Python/Ruby tramite l'interfaccia REST di Hub di notifica, come descritto nell'argomento API REST degli hub di notificadi MSDN.In general, you can access all Notification Hubs features from a Java/PHP/Python/Ruby back-end using the Notification Hub REST interface as described in the MSDN topic Notification Hubs REST APIs. L'SDK per Java fornisce un semplice wrapper per le interfacce REST in Java.This Java SDK provides a thin wrapper over these REST interfaces in Java.

L'SDK attualmente supporta:The SDK supports currently:

  • CRUD in Hub di notificaCRUD on Notification Hubs
  • CRUD in RegistrazioniCRUD on Registrations
  • Gestione dell'installazioneInstallation Management
  • Importazione/esportazione di registrazioniImport/Export Registrations
  • Invii regolariRegular Sends
  • Invii pianificatiScheduled Sends
  • Operazioni asincrone tramite Java NIOAsync operations via Java NIO
  • Piattaforme supportate: APNS (iOS), GCM (Android), WNS (app di Windows Store), MPNS(Windows Phone), ADM (Amazon Kindle Fire), Baidu (Android senza servizi Google)Supported platforms: APNS (iOS), GCM (Android), WNS (Windows Store apps), MPNS(Windows Phone), ADM (Amazon Kindle Fire), Baidu (Android without Google services)

Uso dell'SDKSDK Usage

Compilazione e creazioneCompile and build

Usare MavenUse Maven

Per creare:To build:

mvn package

CodiceCode

CRUD di Hub di notificaNotification Hub CRUDs

Creare un oggetto NamespaceManager:Create a NamespaceManager:

NamespaceManager namespaceManager = new NamespaceManager("connection string")

Creare un hub di notifica:Create Notification Hub:

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

OppureOR

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

Ottenere un hub di notifica:Get Notification Hub:

hub = namespaceManager.getNotificationHub("hubname");

Aggiornare un hub di notifica:Update Notification Hub:

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

Eliminare un hub di notifica:Delete Notification Hub:

namespaceManager.deleteNotificationHub("hubname");

CRUD di registrazioneRegistration CRUDs

Creare un client di Hub di notifica:Create a Notification Hub client:

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

Creare una registrazione per Windows:Create Windows registration:

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

Creare una registrazione per iOS:Create iOS registration:

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

Analogamente, è possibile creare registrazioni per Android (GCM), Windows Phone (MPNS) e Kindle Fire (ADM).Similarly you can create registrations for Android (GCM), Windows Phone (MPNS), and Kindle Fire (ADM).

Creare registrazioni modello:Create template registrations:

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

Creare registrazioni usando il modello create registrationid + upsertCreate registrations using create registrationid + upsert pattern

Rimuove i duplicati causati dalle risposte perse se gli ID di registrazione sono stati archiviati nel dispositivo:Removes duplicates due to any lost responses if storing registration ids on the device:

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

Aggiornare registrazioni:Update registrations:

hub.updateRegistration(reg);

Eliminare registrazioni:Delete registrations:

hub.deleteRegistration(regid);

Effettuare query di registrazioni:Query registrations:

  • Ottenere una singola registrazione:Get single registration:

    hub.getRegistration(regid);hub.getRegistration(regid);

  • Ottenere tutte le registrazioni nell'hub:Get all registrations in hub:

    hub.getRegistrations();hub.getRegistrations();

  • Ottenere registrazioni con tag:Get registrations with tag:

    hub.getRegistrationsByTag("myTag");hub.getRegistrationsByTag("myTag");

  • Ottenere registrazioni per canale:Get registrations by channel:

    hub.getRegistrationsByChannel("devicetoken");hub.getRegistrationsByChannel("devicetoken");

Tutte le query di raccolta supportano i token $top e di continuazione.All collection queries support $top and continuation tokens.

Uso dell'API di installazioneInstallation API usage

L'API di installazione rappresenta un meccanismo alternativo per la gestione delle registrazioni.Installation API is an alternative mechanism for registration management. Il mantenimento di più registrazioni non è semplice e può facilmente essere eseguito in maniera errata o inefficace, pertanto ora è possibile usare un SINGOLO oggetto di installazione.Instead of maintaining multiple registrations which is not trivial and may be easily done wrongly or inefficiently, it is now possible to use a SINGLE Installation object. L'installazione contiene tutti gli elementi necessari: il canale push (token del dispositivo), tag, modelli, riquadri secondari (per WNS e APN).Installation contains everything you need: push channel (device token), tags, templates, secondary tiles (for WNS and APNS). Non è più necessario chiamare il servizio per ottenere l'Id. È sufficiente generare un GUID o qualsiasi altro identificatore, mantenerlo nel dispositivo e inviarlo al back-end con il canale push (token del dispositivo).You don't need to call the service to get Id anymore - just generate GUID or any other identifier, keep it on device and send to your backend together with push channel (device token). Nel back-end, effettuare una singola chiamata: CreateOrUpdateInstallation, del tutto idempotente, per cui se necessario è possibile ritentare.On the backend you should only do a single call: CreateOrUpdateInstallation, it is fully idempotent, so feel free to retry if needed.

Un esempio per Amazon Kindle Fire è simile al seguente:As example for Amazon Kindle Fire it looks like this:

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

Per aggiornarlo:If you want to update it:

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

Per scenari avanzati è possibile usare la funzionalità di aggiornamento parziale, che consente di modificare solo determinate proprietà dell'oggetto di installazione.For advanced scenarios we have partial update capability which allows to modify only particular properties of the installation object. L'aggiornamento parziale è essenzialmente un subset di operazioni Patch JSON che è possibile eseguire in un oggetto di installazione.Basically partial update is subset of JSON Patch operations you can run against Installation object.

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

Eliminare l'installazione:Delete Installation:

hub.deleteInstallation(installation.getInstallationId());

Le operazioni CreateOrUpdate, Patch e Delete saranno coerenti con l'operazione Get.CreateOrUpdate, Patch and Delete are eventually consistent with Get. L'operazione richiesta passa alla coda di sistema durante la chiamata e verrà eseguita in background.Your requested operation just goes to the system queue during the call and will be executed in background. Si noti che l'operazione Get non è progettata per lo scenario di runtime principale, ma solo per il debug e la risoluzione dei problemi ed è strettamente limitata dal servizio.Note that Get is not designed for main runtime scenario but just for debug and troubleshooting purposes, it is tightly throttled by the service.

Il flusso di invio per le installazioni è identico a quello delle registrazioni.Send flow for Installations is the same as for Registrations. È stata introdotta un'opzione per indirizzare la notifica all'installazione specifica: per farlo, usare il tag "InstallationId: {desired-id}".We've just introduced an option to target notification to the particular Installation - just use tag "InstallationId:{desired-id}". Nel caso riportato sopra l'aspetto dovrebbe essere simile al seguente:For case above it would look like this:

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

Per uno dei diversi modelli:For one of several templates:

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

Pianificare le notifiche (disponibile per il livello STANDARD)Schedule Notifications (available for STANDARD Tier)

Si tratta di un invio normale ma con un parametro aggiuntivo, scheduledTime, che indica quando deve essere recapitata la notifica.The same as regular send but with one additional parameter - scheduledTime which says when notification should be delivered. Il servizio accetta qualsiasi data e ora da 5 minuti a sette giorni a partire dalla data e ora correnti.Service accepts any point of time between now + 5 minutes and now + 7 days.

Pianificare una notifica nativa di Windows:Schedule a Windows native notification:

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

Importazione/esportazione (disponibile per il livello STANDARD)Import/Export (available for STANDARD Tier)

Talvolta è necessario eseguire un'operazione di massa nelle registrazioni.Sometimes it is required to perform bulk operation against registrations. In genere si tratta dell'integrazione con un altro sistema o di una correzione di grandi dimensioni, ad esempio per l'aggiornamento di tag.Usually it is for integration with another system or just a massive fix to say update the tags. Se si ha a che fare con migliaia di registrazioni, non è consigliabile usare il flusso Get/Update.It is strongly not recommended to use Get/Update flow if we are talking about thousands of registrations. La soluzione appropriata per tale scenario è la funzionalità di importazione/esportazione.Import/Export capability is designed to cover the scenario. Essenzialmente è necessario fornire un accesso a un contenitore BLOB dell'account di archiviazione come origine dei dati in ingresso e come percorso per l'output.Basically you provide an access to some blob container under your storage account as a source of incoming data and location for output.

Inviare il processo di esportazione:Submit export job:

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

Inviare il processo di importazione:Submit import job:

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

Attendere fino al completamento del processo:Wait until job is done:

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

Ottenere tutti i processi:Get all jobs:

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

URI con firma SAS : l'URL di un file BLOB o di un contenitore BLOB con un insieme di parametri come le autorizzazioni e l'ora di scadenza e con la firma di tutti questi elementi effettuata usando la chiave della firma di accesso condiviso dell'account.URI with SAS signature: This is the URL of some blob file or blob container plus set of parameters like permissions and expiration time plus signature of all these things made using account's SAS key. L'SDK per Java di Archiviazione di Azure dispone di funzionalità avanzate, compresa la creazione di tale tipo di URI.Azure Storage Java SDK has rich capabilities including creation of such kind of URIs. In alternativa è possibile esaminare la classe di test ImportExportE2E (dal percorso Github) che include un'implementazione molto semplice e compatta dell'algoritmo di firma.As simple alternative you can take a look at ImportExportE2E test class (from the github location) which has very basic and compact implementation of signing algorithm.

Inviare notificheSend Notifications

L'oggetto notifica è semplicemente un corpo con intestazioni ed esistono alcuni metodi di utilità che consentono la creazione di notifiche modello e notifiche native.The Notification object is simply a body with headers, some utility methods help in building the native and template notifications objects.

  • Windows Store e Windows Phone 8.1 (non Silverlight)Windows Store and Windows Phone 8.1 (non-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);
    
  • iOSiOS

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

      String message = "{\"data\":{\"msg\":\"Hello from Java!\"}}";
      Notification n = Notification.createGcmNotification(message);
      hub.sendNotification(n);
    
  • Windows Phone 8.0 e 8.1 SilverlightWindows Phone 8.0 and 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 FireKindle Fire

      String message = "{\"data\":{\"msg\":\"Hello from Java!\"}}";
      Notification n = Notification.createAdmNotification(message);
      hub.sendNotification(n);
    
  • Inviare a tagSend to Tags

      Set<String> tags = new HashSet<String>();
      tags.add("boo");
      tags.add("foo");
      hub.sendNotification(n, tags);
    
  • Inviare a espressione tagSend to tag expression

      hub.sendNotification(n, "foo && ! bar");
    
  • Inviare una notifica modelloSend template notification

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

Quando si esegue il codice Java, dovrebbe essere visualizzata una notifica sul dispositivo di destinazione.Running your Java code should now produce a notification appearing on your target device.

Passaggi successiviNext Steps

In questo argomento è stato illustrato come creare un semplice client REST Java per Hub di notifica.In this topic we showed how to create a simple Java REST client for Notification Hubs. A questo punto è possibile:From here you can: