Java から Notification Hubs を使用する方法How to use Notification Hubs from Java

このトピックでは、新しい Azure Notification Hub Java SDK の主な機能について説明します。Azure Notification Hub Java SDK は、完全にサポートされている公式の SDK です。This topic describes the key features of the new fully supported official Azure Notification Hub Java SDK. このプロジェクトはオープンソースのプロジェクトであるため、Java SDK で SDK コード全体を表示できます。This project is an open-source project and you can view the entire SDK code at Java SDK.

MSDN のトピック「 Notification Hubs の REST API」の説明にあるように、通常は、Notification Hub REST インターフェイスを使用して、Java/PHP/Python/Ruby バックエンドから Notification Hubs のすべての機能にアクセスできます。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. この Java SDK は、これらの REST インターフェイスを使用して、Java で Thin ラッパーを提供します。This Java SDK provides a thin wrapper over these REST interfaces in Java.

現在、SDK のサポート対象は次のとおりです。The SDK currently supports:

  • Notification Hubs の CRUDCRUD on Notification Hubs
  • 登録の CRUDCRUD on Registrations
  • インストール管理Installation Management
  • 登録のインポート/エクスポートImport/Export Registrations
  • 通常の送信Regular Sends
  • スケジュールされた送信Scheduled Sends
  • Java NIO を使用した非同期操作Async operations via Java NIO
  • サポート対象のプラットフォーム:APNS (iOS)、FCM (Android)、WNS (Windows ストア アプリ)、MPNS (Windows Phone)、ADM (Amazon Kindle Fire)、Baidu (Google のサービスを使用しない Android)Supported platforms: APNS (iOS), FCM (Android), WNS (Windows Store apps), MPNS(Windows Phone), ADM (Amazon Kindle Fire), Baidu (Android without Google services)

SDK の使用例SDK Usage

コンパイルとビルドCompile and build

MavenUse Maven

次のコードを使用してビルドします。To build:

mvn package

コードCode

Notification Hub の CRUDNotification Hub CRUDs

NamespaceManager を作成する:Create a NamespaceManager:

NamespaceManager namespaceManager = new NamespaceManager("connection string")

Notification Hub を作成する:Create Notification Hub:

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

OROR

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

Notification Hub を取得する:Get Notification Hub:

hub = namespaceManager.getNotificationHub("hubname");

Notification Hub を更新する:Update Notification Hub:

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

Notification Hub を削除する:Delete Notification Hub:

namespaceManager.deleteNotificationHub("hubname");

登録の CRUDRegistration CRUDs

Notification Hub クライアントを作成する:Create a Notification Hub client:

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

Windows の登録を作成する:Create Windows registration:

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

iOS の登録を作成する:Create iOS registration:

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

同様に、Android (FCM)、Windows Phone (MPNS)、および Kindle Fire (ADM) の登録を作成できます。Similarly you can create registrations for Android (FCM), Windows Phone (MPNS), and Kindle Fire (ADM).

テンプレートの登録を作成する:Create template registrations:

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

登録 ID およびアップサート パターンの作成を使用して登録を作成する:Create registrations using create registration ID + upsert pattern:

デバイスで登録 ID を格納すると応答が失われる場合があるため、重複を削除します。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);

登録を更新する:Update registrations:

hub.updateRegistration(reg);

登録を削除する:Delete registrations:

hub.deleteRegistration(regid);

登録をクエリする:Query registrations:

  • 1 つの登録を取得する:Get single registration:
hub.getRegistration(regid);
  • ハブ内のすべての登録を取得する:Get all registrations in hub:
hub.getRegistrations();
  • タグ付きの登録を取得する:Get registrations with tag:
hub.getRegistrationsByTag("myTag");
  • チャネルにより登録を取得する:Get registrations by channel:
hub.getRegistrationsByChannel("devicetoken");

すべてのコレクション クエリでは $top トークンと継続トークンがサポートされます。All collection queries support $top and continuation tokens.

インストール API の使用例Installation API usage

インストール API は登録管理の代替メカニズムです。Installation API is an alternative mechanism for registration management. 複数の登録を保持する (これは大変な作業であり、簡単に間違って、または非効率的に実行される可能性があります) 代わりに、単一インストール オブジェクトを使用できるようになりました。Instead of maintaining multiple registrations, which are not trivial and may be easily done incorrectly or inefficiently, it is now possible to use a SINGLE Installation object.

Installation には、プッシュ チャネル (デバイス トークン)、タグ、テンプレート、セカンダリ タイル (WNS および APNS 用) などの必要な情報がすべて格納されます。Installation contains everything you need: push channel (device token), tags, templates, secondary tiles (for WNS and APNS). ID を取得するためにサービスを呼び出す必要はもうありません。GUID またはその他の任意の識別子を生成してデバイス上に保持し、プッシュ チャネル (デバイス トークン) と共にバックエンドに送信するだけです。You don't need to call the service to get ID anymore - just generate GUID or any other identifier, keep it on the device and send to your backend together with push channel (device token).

バックエンドでは、CreateOrUpdateInstallation を 1 回呼び出すだけで済みます。これは完全にべき等であるため、必要に応じて自由に再試行できます。On the backend, you should only do a single call to CreateOrUpdateInstallation; it is fully idempotent, so feel free to retry if needed.

Amazon Kindle Fire の例を次に示します。As example for Amazon Kindle Fire:

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

更新する場合は、次のようになります。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);

高度なシナリオの場合は、インストール オブジェクトの特定のプロパティのみを変更できる部分更新機能を使用します。For advanced scenarios, use the partial update capability, which allows to modify only particular properties of the installation object. 部分更新は、インストール オブジェクトに対して実行できる JSON Patch 操作のサブセットです。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);

Installation を削除する:Delete Installation:

hub.deleteInstallation(installation.getInstallationId());

CreateOrUpdatePatchDelete は最終的に Get と整合性がとれます。CreateOrUpdate, Patch, and Delete are eventually consistent with Get. 要求された操作は、単に呼び出し中にシステム キューに移動し、バックグラウンドで実行されます。Your requested operation just goes to the system queue during the call and is executed in background. Get はメインのランタイム シナリオのためではなく、単にデバッグやトラブルシューティングのために設計されているため、サービスによって密接に調整されます。Get is not designed for main runtime scenario but just for debug and troubleshooting purposes, it is tightly throttled by the service.

インストールの送信フローは登録の場合と同じです。Send flow for Installations is the same as for Registrations. 通知を特定のインストールに送信するには、タグ "InstallationId:{desired-id}" を使用するだけです。To target notification to the particular Installation - just use tag "InstallationId:{desired-id}". この場合、コードは次のようになります。For this case, the code is:

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

複数のテンプレートのうちの 1 つを使用する場合、コードは次のようになります。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");

通知のスケジュール設定 (標準階層の場合に使用可能)Schedule Notifications (available for STANDARD Tier)

通常の送信と同じですが、通知がいつ配信されるかを示す scheduledTime という 1 つのパラメーターが追加されています。The same as regular send but with one additional parameter - scheduledTime, which says when notification should be delivered. サービスは、現在 + 5 分~現在 + 7 日の任意の時点を受け入れます。Service accepts any point of time between now + 5 minutes and now + 7 days.

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

インポート/エクスポート (標準階層の場合に使用可能)Import/Export (available for STANDARD Tier)

登録に対する一括操作の実行が必要な場合があります。You may need to perform bulk operation against registrations. 通常は、別のシステムとの統合や、タグを更新するための大規模な修正を行う場合です。Usually it is for integration with another system or a massive fix to update the tags. 数千の登録が関連している場合、Get/Update フローの使用はお勧めできません。We don't recommend using the Get/Update flow if thousands of registrations are involved. システムのインポート/エクスポート機能は、このようなシナリオに対応しています。The system's Import/Export capability is designed to cover the scenario. 受信データのソースおよび出力のための場所として、ストレージ アカウントの BLOB コンテナーへのアクセスを提供します。You'll provide access to a blob container under your storage account as a source of incoming data and location for output.

エクスポート ジョブを送信する:Submit an export job:

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

インポート ジョブを送信する:Submit an 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);

ジョブが完了するまで待機する:Wait until a job is done:

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

すべてのジョブを取得する:Get all jobs:

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

SAS 署名を含む URI:URI with SAS signature:

この URL は、ある BLOB ファイルまたは BLOB コンテナーの URL に、一連のパラメーター (アクセス許可や期限切れ日時など) と、アカウントの SAS キーを使用して作成されたこれらのすべてのものの署名を加えたものです。This URL is the URL of a blob file or blob container plus a set of parameters like permissions and expiration time plus signature of all these things made using account's SAS key. Azure Storage Java SDK には、これらの URI を作成を含む豊富な機能が用意されています。Azure Storage Java SDK has rich capabilities including creation of these URIs. 簡単な代替手段として、署名アルゴリズムの基本的でコンパクトな実装を含む (GitHub の場所にある) ImportExportE2E テスト クラスを参照します。As simple alternative, take a look at the ImportExportE2E test class (from the GitHub location) which has basic and compact implementation of signing algorithm.

通知の送信Send Notifications

Notification オブジェクトはヘッダー付きの本文にすぎません。一部のユーティリティ メソッドはネイティブ オブジェクトとテンプレート通知オブジェクトのビルドに役立ちます。The Notification object is simply a body with headers, some utility methods help in building the native and template notifications objects.

  • Windows ストアおよび Windows Phone 8.1 (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.createFcmNotification(message);
hub.sendNotification(n);
  • Windows Phone 8.0 および 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);
  • タグに送信するSend to Tags
Set<String> tags = new HashSet<String>();
tags.add("boo");
tags.add("foo");
hub.sendNotification(n, tags);
  • タグ式に送信するSend to tag expression
hub.sendNotification(n, "foo && ! bar");
  • テンプレート通知を送信するSend 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);

Java コードを実行すると、ターゲット デバイスに表示される通知が生成されます。Running your Java code should now produce a notification appearing on your target device.

次のステップNext Steps

このトピックでは、Notification Hubs 用の単純な Java REST クライアントを作成する方法を示しました。This topic showed you how to create a simple Java REST client for Notification Hubs. ここでは、次の操作を実行できます。From here you can: