登録管理Registration management

概要Overview

ここでは、プッシュ通知を受信するために通知ハブにデバイスを登録する方法について説明します。This topic explains how to register devices with notification hubs in order to receive push notifications. また、登録の概要、デバイスを登録するための 2 つの主要パターン (デバイスから通知ハブに直接登録する方法と、アプリケーション バックエンド経由で登録する方法) についても説明します。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.

デバイス登録の概要What is device registration

Notification Hub にデバイスを登録するには、登録またはインストールを使用します。Device registration with a Notification Hub is accomplished using a Registration or Installation.

登録Registrations

登録によって、デバイスのプラットフォーム通知サービス (PNS) ハンドルが、タグや場合によってはテンプレートに関連付けられます。A registration associates the Platform Notification Service (PNS) handle for a device with tags and possibly a template. PNS ハンドルは、ChannelURI、デバイス トークン、または FCM 登録 ID の場合があります。タグは、通知を正しいデバイス ハンドル セットにルーティングするために使用されます。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. 詳細については、「 ルーティングとタグ式」を参照してください。For more information, see Routing and Tag Expressions. テンプレートは、登録ごとの変換を実装するために使用されます。Templates are used to implement per-registration transformation. 詳細については、「 テンプレート」を参照してください。For more information, see Templates.

注意

Azure Notification Hubs では、デバイスごとに最大 60 個のタグがサポートされます。Azure Notification Hubs supports a maximum of 60 tags per device.

インストールInstallations

インストールは、プッシュ関連の一連のプロパティを含む強化された登録です。An Installation is an enhanced registration that includes a bag of push related properties. また、デバイス登録の最新の優れた方法です。It is the latest and best approach to registering your devices. ただし、クライアント側の .NET SDK (バックエンド操作用の Notification Hub SDK) ではまだサポートされていません。However, it is not supported by client-side .NET SDK (Notification Hub SDK for backend operations) as of yet. つまり、クライアント デバイス自体から登録する場合は、インストールをサポートする Notification Hubs REST API を使用する必要があります。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. バックエンド サービスを使用する場合は、 バックエンド操作用の Notification Hub SDKを使用できます。If you are using a backend service, you should be able to use Notification Hub SDK for backend operations.

次に、インストールを使用する方法の主な利点について説明します。The following are some key advantages to using installations:

  • インストールの作成または更新は、完全にべき等です。Creating or updating an installation is fully idempotent. そのため、重複した登録について心配することなく、再試行できます。So you can retry it without any concerns about duplicate registrations.
  • このインストール モデルは、特定のデバイスに通知を直接送信できるようになる特殊なタグ形式 ($InstallationId:{INSTALLATION_ID}) をサポートしています。The installation model supports a special tag format ($InstallationId:{INSTALLATION_ID}) that enables sending a notification directly to the specific device. たとえば、アプリのコードがこの特定のデバイスのインストール ID joe93developer を設定している場合、開発者は $InstallationId:{joe93developer} タグに通知を送信するときにこのデバイスを対象にすることができます。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. こうすることで、コードを追加することなく、特定のデバイスを対象にすることができます。This enables you to target a specific device without having to do any additional coding.
  • また、インストールを使用することで、部分的な登録の更新を実行できます。Using installations also enables you to do partial registration updates. インストールの部分的な更新は、 JSON-Patch 標準を使用して、PATCH メソッドで要求されます。The partial update of an installation is requested with a PATCH method using the JSON-Patch standard. これは、登録時にタグを更新する場合に役立ちます。This is useful when you want to update tags on the registration. 登録全体を取得し、前のタグすべてを再送信する必要はありません。You don't have to pull down the entire registration and then resend all the previous tags again.

インストールには、次のプロパティを含めることができます。An installation can contain the following properties. インストール プロパティの完全なリストについては、REST API でのインストールの作成または上書きに関するページ、またはインストール プロパティに関するページを参照してください。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: [] }
            }
        }
    }
}

注意

既定では、登録とインストールに有効期限はありません。By default, registrations and installations do not expire.

登録とインストールには、各デバイス/チャネルの有効な PNS ハンドルを含める必要があります。Registrations and installations must contain a valid PNS handle for each device/channel. PNS ハンドルはデバイスのクライアント アプリでのみ取得できるので、クライアント アプリを使用してそのデバイスに直接登録する方法があります。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. 一方、タグに関連するセキュリティの考慮事項とビジネス ロジックによっては、アプリのバックエンドでデバイス登録を管理する作業が必要になる可能性があります。On the other hand, security considerations and business logic related to tags might require you to manage device registration in the app back-end.

テンプレートTemplates

テンプレートを使用する場合、デバイスのインストールでは、そのデバイスに関連付けられたすべてのテンプレートも JSON 形式で保持されます (上のサンプルを参照)。If you want to use Templates, the device installation also holds all templates associated with that device in a JSON format (see sample above). テンプレート名は、1 つのデバイスに複数のテンプレートを対象にすることができます。The template names help target different templates for the same device.

各テンプレート名が、テンプレートの本文とオプションの一連のタグにマップされます。Each template name maps to a template body and an optional set of tags. さらに、各プラットフォームには、テンプレート プロパティが他にもある場合があります。Moreover, each platform can have additional template properties. (WNS を使用する) Windows ストアと (MPNS を使用する) Windows Phone 8 の場合、その他のヘッダー セットをテンプレートに含めることができます。For Windows Store (using WNS) and Windows Phone 8 (using MPNS), an additional set of headers can be part of the template. APNs の場合、expiry プロパティを定数またはテンプレート式に設定することができます。In the case of APNs, you can set an expiry property to either a constant or to a template expression. インストール プロパティの一覧については、インストール プロパティの一覧については、 REST でインストールを作成または上書きする方法 に関するトピックを参照してください。For a complete listing of the installation properties see, Create or Overwrite an Installation with REST topic.

Windows ストア アプリのセカンダリ タイルSecondary Tiles for Windows Store Apps

Windows ストア クライアント アプリケーションの場合、セカンダリ タイルに通知を送信する処理は、プライマリ タイルに送信する場合と同じです。For Windows Store client applications, sending notifications to secondary tiles is the same as sending them to the primary one. この処理もインストールでサポートされています。This is also supported in installations. セカンダリ タイルには、クライアント アプリ上の SDK が透過的に処理する別の ChannelUri があります。Secondary tiles have a different ChannelUri, which the SDK on your client app handles transparently.

SecondaryTiles ディクショナリは、Windows ストア アプリで SecondaryTiles オブジェクトを作成するために使用されたものと同じ TileId を使用します。The SecondaryTiles dictionary uses the same TileId that is used to create the SecondaryTiles object in your Windows Store app. プライマリ タイルの ChannelUri と同様に、セカンダリ タイルの ChannelUris は常に変化する可能性があります。As with the primary ChannelUri, ChannelUris of secondary tiles can change at any moment. 通知ハブのインストールを最新の状態に保つには、デバイスがセカンダリ タイルの最新の ChannelUris を使用して更新する必要があります。In order to keep the installations in the notification hub updated, the device must refresh them with the current ChannelUris of the secondary tiles.

デバイスからの登録管理Registration management from the device

クライアント アプリからデバイス登録を管理する場合、バックエンドは通知の送信のみを担当します。When managing device registration from client apps, the backend is only responsible for sending notifications. クライアント アプリは PNS ハンドルを最新の状態に維持し、タグを登録します。Client apps keep PNS handles up-to-date, and register tags. このパターンについて次の図で説明します。The following picture illustrates this pattern.

デバイスは、まず PNS から PNS ハンドルを取得してから、通知ハブに直接登録します。The device first retrieves the PNS handle from the PNS, then registers with the notification hub directly. 登録に成功すると、アプリ バックエンドからその登録に対して通知を送信できるようになります。After the registration is successful, the app backend can send a notification targeting that registration. 通知の送信方法の詳細については、 ルーティングとタグ式に関するページを参照してください。For more information about how to send notifications, see Routing and Tag Expressions.

この場合は、リッスン権限のみを使用して、デバイスから通知ハブにアクセスします。In this case, you use only Listen rights to access your notification hubs from the device. 詳細については、 セキュリティに関するページを参照してください。For more information, see Security.

デバイスからの登録が最も簡単な方法ですが、いくつか欠点があります。Registering from the device is the simplest method, but it has some drawbacks:

  • クライアント アプリがタグを更新できるのは、そのアプリがアクティブなときだけです。A client app can only update its tags when the app is active. たとえば、ユーザーがスポーツ チームに関連するタグを登録しているデバイスを 2 台持っている状態で、1 台目のデバイスが追加のタグ (Seahawks など) を登録すると、2 台目のデバイスを次に実行するまで、Seahawks に関する通知は 2 台目のデバイスに送信されません。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. さらに一般的には、タグが複数のデバイスの影響を受ける場合、バックエンドからのタグ管理が推奨される選択肢です。More generally, when tags are affected by multiple devices, managing tags from the backend is a desirable option.
  • アプリはハッキングされる可能性があるので、セクション「タグレベルのセキュリティ」で説明しているように、特定のタグに対する登録をセキュリティで保護する際に、特別な注意が必要です。Since apps can be hacked, securing the registration to specific tags requires extra care, as explained in the section “Tag-level security.”

インストールを使用してデバイスから通知ハブに登録するコード例Example code to register with a notification hub from a device using an installation

現時点では、 Notification Hubs REST APIを使用する必要があります。At this time, this is only supported using the Notification Hubs REST API.

また、インストールを更新する場合は、 JSON-Patch 標準 の PATCH メソッドを使用することもできます。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();
}

登録を使用してデバイスから通知ハブに登録するコード例Example code to register with a notification hub from a device using a registration

これらのメソッドで、呼び出すデバイスの登録を作成または更新します。These methods create or update a registration for the device on which they are called. つまり、ハンドルまたはタグを更新するには、登録全体を上書きする必要があります。This means that in order to update the handle or the tags, you must overwrite the entire registration. 登録は一時的なものなので、そのデバイスに必要な最新のタグを保存できる信頼性の高いストアを常に用意する必要があります。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");
}

バックエンドからの登録管理Registration management from a backend

バックエンドから登録を管理するには、追加のコードを作成する必要があります。Managing registrations from the backend requires writing additional code. デバイスのアプリは、アプリが起動するたびに、最新の PNS ハンドル (タグとテンプレートも) をバックエンドに提供する必要があります。また、バックエンドは、通知ハブでそのハンドルを更新する必要があります。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. この設計について次の図で説明します。The following picture illustrates this design.

バックエンドから登録を管理する利点として、デバイスの対応するアプリがアクティブではない場合でも、登録に対してタグを変更できることと、タグを登録に追加する前にクライアント アプリを認証できることがあります。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.

インストールを使用してバックエンドから通知ハブに登録するコード例Example code to register with a notification hub from a backend using an installation

前述のように、クライアント デバイスは、PNS ハンドルと関連するインストール プロパティを取得し、バックエンドで、登録やタグの承認などを行うカスタム API を呼び出すことができます。バックエンドは、バックエンド操作に Notification Hub SDK を利用できます。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.

また、インストールを更新する場合は、 JSON-Patch 標準 の PATCH メソッドを使用することもできます。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);
}

登録 ID を使用してデバイスから通知ハブに登録するコード例Example code to register with a notification hub from a device using a registration ID

アプリ バックエンドから、登録に対して基本の CRUDS 操作を実行できます。From your app backend, you can perform basic CRUDS operations on registrations. 例: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);

バックエンドは、登録の更新が複数ある場合のコンカレンシーに対応する必要があります。The backend must handle concurrency between registration updates. Service Bus は、登録管理向けにオプティミスティック コンカレンシーを提供しています。Service Bus offers optimistic concurrency control for registration management. HTTP レベルでは、この処理は登録管理操作に対して ETag を使用して実装されます。At the HTTP level, this is implemented with the use of ETag on registration management operations. この機能は、Microsoft SDK から透過的に使用されます。コンカレンシーの理由で更新が拒否された場合は、例外がスローされます。This feature is transparently used by Microsoft SDKs, which throw an exception if an update is rejected for concurrency reasons. アプリ バックエンドは、これらの例外を処理し、必要に応じて更新を再試行する役割を果たします。The app backend is responsible for handling these exceptions and retrying the update if necessary.