プッシュ通知サービスの要求ヘッダーと応答ヘッダー (Windows ランタイムアプリ)

[アーティクル]
12/22/2015

[ この記事は、Windows ランタイムアプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]

ここでは、プッシュ通知を送るために必要なサービス間 Web API とプロトコルについて説明します。

プッシュ通知、Windows プッシュ通知サービス (WNS) の概念、要件、動作の概念の説明については、「Windows プッシュ通知サービス (WNS) の概要」をご覧ください。

アクセストークンの要求と受信

このセクションでは、WNS に対して認証する際に関連する要求パラメーターと応答パラメーターについて説明します。

アクセストークン要求

クラウドサービスの認証を行い、WNS からアクセストークンを取得するために、HTTP 要求が WNS に送られます。要求は、Secure Sockets Layer (SSL) を使って以下の完全修飾ドメイン名 (FQDN) に対して発行されます。

https://login.live.com/accesstoken.srf

アクセストークン要求パラメーター

クラウドサービスは、"application/x-www-form-urlencoded" の形式を使って、以下の必須パラメーターを HTTP 要求の本文で送ります。すべてのパラメーターが URL エンコードされるようにする必要があります。

パラメーター	必須/省略可能	説明
grant_type	必須	"client_credentials" に設定する必要があります。
client_id	必須	Windows ストアにアプリを登録したときに割り当てられたクラウドサービスのパッケージセキュリティ識別子 (SID)。
client_secret	必須	Windows ストアにアプリを登録したときに割り当てられたクラウドサービスの秘密鍵。
scope	必須	以下のとおり設定する必要があります。 Windows: "notify.windows.com" Windows Phone: "notify.windows.com" または "s.notify.live.net"

アクセストークン応答

WNS はクラウドサービスを認証し、成功した場合、"200 OK" (アクセストークンを含む) を表示して応答します。それ以外の場合、WNS は、OAuth 2.0 プロトコルの草案で説明されているように、適切な HTTP エラーコードを表示して応答します。

アクセストークン応答パラメーター

クラウドサービスが正常に認証された場合、アクセストークンが HTTP 応答で返されます。このアクセストークンは、有効期限切れになるまで通知要求で使用できます。HTTP 応答では、"application/json" メディアタイプが使われます。

パラメーター	必須/省略可能	説明
access_token	必須	クラウドサービスが通知を送るときに使われるアクセストークン。
token_type	省略可能	常に "bearer" として返されます。

応答コード

HTTP 応答コード	説明
200 OK	要求は成功しました。
400 Bad Request	認証が失敗しました。応答パラメーターについては、OAuth の草案の Request for Comments (RFC) を参照してください。

例

以下は、成功した認証の応答の例を示しています。

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

通知要求の送信と応答の受信

このセクションでは、通知を配信するための WNS への HTTP 要求に含まれるヘッダーと、応答に含まれるヘッダーについて説明します。

通知要求を送信する
通知応答を送信する
サポートされない HTTP 機能

通知要求を送信する

通知要求を送るときに、呼び出し元のアプリは、チャネルの Uniform Resource Identifier (URI) 宛てに SSL を介して HTTP 要求を行います。"Content-Length" は、要求で指定する必要がある標準の HTTP ヘッダーです。その他すべての標準のヘッダーは、省略可能かサポートされていません。

さらに、ここに示されているカスタム要求ヘッダーを通知要求で使用できます。ヘッダーには必須のものと省略可能なものがあります。

要求パラメーター

ヘッダー名	必須/省略可能	説明
Authorization	必須	通知要求の認証に使われる標準の HTTP 承認ヘッダー。クラウドサービスはアクセストークンをこのヘッダーに指定します。
Content-Type	必須	標準の HTTP 承認ヘッダー。トースト、タイル、バッジ通知では、このヘッダーは "text/xml" に設定する必要があります。直接通知では、このヘッダーは "application/octet-stream" に設定する必要があります。
Content-Length	必須	要求のペイロードのサイズを示すための標準の HTTP 承認ヘッダー。
X-WNS-Type	必須	ペイロードの通知の種類 (タイル、トースト、バッジ、または直接) を定義します。
X-WNS-Cache-Policy	省略可能	通知のキャッシュを有効または無効にします。このヘッダーは、タイル、バッジ、直接通知にのみ適用されます。
X-WNS-RequestForStatus	省略可能	通知応答でデバイスの状態と WNS の接続状態を要求します。
X-WNS-Tag	省略可能	通知に識別ラベルを提供するために使われる文字列。通知キューをサポートするタイルで使われます。このヘッダーは、タイル通知にのみ適用されます。
X-WNS-TTL	省略可能	Time to Live (TTL) を指定する秒単位の整数値。
X-WNS-SuppressPopup	省略可能	Windows Phone のみ: トーストを表示せず、アクションセンターに直接トースト通知を配信します。
X-WNS-Group	省略可能	Windows Phone のみ: X-WNS-Tag ヘッダーを使ってアクションセンターで通知をグループ化します。
X-WNS-Match	状況により必要	Windows Phone のみ: HTTP DELETE メソッドを使ってアクションセンターからトースト通知を削除する場合に、対象の特定に必要になります。

重要な注意

Content-Length および Content-Type のみが、他の標準ヘッダーが要求に含まれていたかどうかにかかわらず、クライアントに配信される通知に含まれる標準の HTTP ヘッダーです。
その他すべての標準の HTTP ヘッダーは、機能がサポートされていない場合、無視されるか、エラーを返します。

承認

OAuth 2.0 の bearer トークンの場合の承認方法に従って、承認ヘッダーを使って呼び出し元の資格情報を指定します。

構文は、文字列リテラル "Bearer"、スペース、アクセストークンの順で構成されます。このアクセストークンは、前に説明したアクセストークン要求を発行して取得します。同じアクセストークンを、有効期限切れになるまで以降の通知要求で使用できます。

このヘッダーは必須です。

Authorization: Bearer <access-token>

X-WNS-Type

以下は、WNS でサポートされる通知の種類です。このヘッダーは、通知の種類と、WNS が通知を処理する方法を示します。通知がクライアントに到達した後で、実際のペイロードがこの指定された種類に照らして検証されます。このヘッダーは必須です。

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

値	説明
wns/badge	タイル上にバッジオーバーレイを作るための通知。通知要求に含まれる Content-Type ヘッダーは、"text/xml" に設定する必要があります。
wns/tile	タイルのコンテンツを更新するための通知。通知要求に含まれる Content-Type ヘッダーは、"text/xml" に設定する必要があります。
wns/toast	クライアントでトーストを表示するための通知。通知要求に含まれる Content-Type ヘッダーは、"text/xml" に設定する必要があります。
wns/raw	カスタムペイロードを含めることができ、アプリに直接配信される通知。通知要求に含まれる Content-Type ヘッダーは、"application/octet-stream" に設定する必要があります。

X-WNS-Cache-Policy

通知のターゲットデバイスがオフラインである場合、WNS は、アプリケーションあたり 1 つのバッジ通知と 1 つのタイル通知をキャッシュします。アプリで通知の循環が有効になっている場合、WNS は最大で 5 つのタイル通知をキャッシュします。既定では、直接通知はキャッシュされません。直接通知のキャッシュを有効にした場合、1 つの直接通知がキャッシュされます。アイテムはキャッシュで無期限に保持されるわけではなく、一定期間が経過すると削除されます。それ以外の場合は、キャッシュされたコンテンツは、デバイスが次にオンラインになったときに配信されます。

このヘッダーは省略可能であり、クラウドサービスで既定のキャッシュ動作を上書きする場合にのみ使います。

X-WNS-Cache-Policy: cache | no-cache

値	説明
cache	既定値。ユーザーがオフラインの場合に、通知がキャッシュされます。これは、タイルとバッジ通知の既定の設定です。
no-cache	ユーザーがオフラインの場合に、通知はキャッシュされません。これは、直接通知の既定の設定です。

X-WNS-RequestForStatus

応答にデバイスの状態と WNS の接続状態を含めるかどうかを指定します。このヘッダーは省略可能です。

X-WNS-RequestForStatus: true | false

値	説明
true	応答でデバイスの状態と通知の状態が返されます。
false	既定値。デバイスの状態と通知の状態は返されません。

X-WNS-Tag

通知に tag ラベルを割り当てます。このタグは、アプリで通知の循環が選ばれている場合に、通知キューにおけるタイルの置き換えポリシーで使われます。このタグを持つ通知がキューに既に存在する場合は、同じタグを持つ新しい通知に置き換えられます。

注このヘッダーはタイル通知を送る場合にのみ使うものであり、省略可能です。

注 Windows Phone ストアアプリでは、X-WNS-Tag ヘッダーと X-WNS-Group ヘッダーを組み合わせると、同じタグが設定されている複数の通知をアクションセンターに表示できます。

X-WNS-Tag: <string value>

値	説明
文字列値	16 文字以下の英数字文字列。

X-WNS-TTL

通知の TTL (有効期限) を指定します。このヘッダーは、通常は必要ありませんが、通知が一定期間後に表示されないようにする場合に使用できます。TTL は、秒単位で指定し、WNS が要求を受け取った時間を基準とします。TTL が指定されている場合、デバイスは、その時間の経過後は通知を表示しません。TTL が短過ぎる場合、通知がまったく表示されなくなる点に注意してください。一般的に、有効期限は少なくとも分単位で測定されます。

このヘッダーは省略可能です。この値を指定しなかった場合には、通知は有効期限切れにならず、標準の通知の置き換えスキームに従って置き換えられます。

X-WNS-TTL: <integer value>

値	説明
整数値	WNS が要求を受け取った後の、秒単位の通知の存続期間。

X-WNS-SuppressPopup

注 Windows Phone ストアアプリでは、トースト通知の UI を非表示にして、アクションセンターに直接通知するオプションを利用できます。通知が表示されずに送られるようになるため、緊急性の低い通知には便利なオプションです。このヘッダーは省略可能であり、Windows Phone のチャネルでのみ使用できます。Windows チャネルでこのヘッダーを使うと、通知がされなくなるため、WNS からエラー応答が送られます。

X-WNS-SuppressPopup: true | false

値	説明
true	アクションセンターにトースト通知が直接送られ、トースト UI が表示されなくなります。
false	既定値。トースト UI が表示され、かつ通知がアクションセンターに追加されます。

X-WNS-Group

注 Windows Phone ストアアプリのアクションセンターでは、異なるグループに分類されている複数のトースト通知を表示するには、同じタグを設定する必要があります。たとえば、レシピ本のアプリを考えてみましょう。各レシピは、タグで識別しています。そのレシピに関するコメントを記載したトーストには、そのレシピのタグと、コメントのグループラベルが付いています。そのレシピの評価を記載したトーストには、そのレシピのタグの他に、評価のグループラベルが付いています。このようにグループラベルが異なる場合でも、アクションセンターではどちらのトースト通知も一度に表示されます。このヘッダーは省略可能です。

X-WNS-Group: <string value>

値	説明
文字列値	16 文字以下の英数字文字列。

X-WNS-Match

注これを HTTP DELETE メソッドと組み合わせて使うと、Windows Phone ストアアプリのアクションセンターから特定のトースト 1 つ、(タグまたはグループに応じて) 複数のトースト、またはトーストすべてを削除できます。このヘッダーでは、グループ、タグ、その両方のいずれかを指定できます。このヘッダーは、HTTP DELETE の通知要求に必要です。この通知要求にペイロードがある場合には、無視されます。

X-WNS-Match: type:wns/toast;group=<string value>;tag=<string value> | type:wns/toast;group=<string value> | type:wns/toast;tag=<string value> | type:wns/toast;all

値	説明
type:wns/toast;group=<文字列値>;tag=<文字列値>	指定されたタグとグループがどちらも設定されている通知を 1 つ削除します。
type:wns/toast;group=<文字列値>	指定されたグループに設定されている通知をすべて削除します。
type:wns/toast;tag=<文字列値>	指定されたタグが設定されている通知をすべて削除します。
type:wns/toast;all	アクションセンターからアプリの通知をすべて削除します。

通知応答を送信する

WNS は、通知要求の処理後に、HTTP メッセージを応答で送ります。このセクションでは、その応答に含まれる可能性があるパラメーターとヘッダーについて説明します。

応答パラメーター

ヘッダー名	必須/省略可能	説明
X-WNS-Debug-Trace	省略可能	問題のレポート時に、問題のトラブルシューティングに利用できるようにログに記録する必要があるデバッグ情報。
X-WNS-DeviceConnectionStatus	省略可能	デバイスの状態。X-WNS-RequestForStatus ヘッダーを使って通知要求で要求された場合にのみ返されます。
X-WNS-Error-Description	省略可能	デバッグに利用できるようにログに記録する必要がある、人間が読み取ることができるエラー文字列。
X-WNS-Msg-ID	省略可能	デバッグ用に使われる、通知の一意の識別子。問題のレポート時に、トラブルシューティングに利用できるようにこの情報をログに記録する必要があります。
X-WNS-Status	省略可能	WNS が正常に通知を受け取り、処理したかどうかを示します。問題のレポート時に、トラブルシューティングに利用できるようにこの情報をログに記録する必要があります。

X-WNS-Debug-Trace

このヘッダーは、有益なデバッグ情報を文字列として返します。開発者が問題のデバッグに利用できるようにこのヘッダーをログに記録することをお勧めします。このヘッダーと X-WNS-Msg-ID ヘッダーは、問題を WNS にレポートする際に必要です。

X-WNS-Debug-Trace: <string value>

値	説明
文字列値	英数字文字列。

X-WNS-DeviceConnectionStatus

このヘッダーは、通知要求の X-WNS-RequestForStatus ヘッダーで要求された場合に、デバイスの状態を呼び出し元のアプリケーションに返します。

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

値	説明
connected	デバイスはオンラインであり、WNS に接続されています。
disconnected	デバイスはオフラインであり、WNS に接続されていません。
tempconnected	デバイスは WNS への接続が一時的に失われています。3G 接続が切断されている場合やノート PC のワイヤレススイッチがオフになっている場合などです。この状態は、通知クライアントプラットフォームからは意図的な切断ではなく一時的な中断として認識されます。

X-WNS-Error-Description

このヘッダーは、デバッグに利用できるようにログに記録する必要がある、人間が読み取ることができるエラー文字列を提供します。

X-WNS-Error-Description: <string value>

値	説明
文字列値	英数字文字列。

X-WNS-Msg-ID

このヘッダーは、呼び出し元に通知の識別子を提供するために使われます。問題のデバッグに利用できるようにこのヘッダーをログに記録することをお勧めします。このヘッダーと X-WNS-Debug-Trace ヘッダーは、問題を WNS にレポートする際に必要です。

X-WNS-Msg-ID: <string value>

値	説明
文字列値	16 文字以下の英数字文字列。

X-WNS-Status

このヘッダーは、WNS が通知要求をどのように処理したかを示します。これは、応答コードを成功または失敗として解釈する代わりに使用できます。

X-WNS-Status: received | dropped | channelthrottled

値	説明
received	通知は WNS によって受け取られ、処理されました。注これは、デバイスが通知を受け取ったことを保証するものではありません。
dropped	エラーのために、またはクライアントが通知を明示的に拒否したために、通知は明示的に破棄されました。デバイスがオフラインである場合、トースト通知も破棄されます。
channelthrottled	アプリサーバーでこの特定のチャネルの速度制限を超えたために、通知は破棄されました。

応答コード

各 HTTP メッセージには、次のいずれかの応答コードが含まれています。WNS では、デバッグに使用できるように開発者が応答コードをログに記録することが推奨されています。開発者は、問題を WNS にレポートする際に、応答コードとヘッダー情報を提供する必要があります。

HTTP 応答コード	説明	推奨されるアクション
200 OK	通知は WNS によって受け入れられました。	必要ありません。
400 Bad Request	1 つ以上のヘッダーが、誤って指定されていたか、別のヘッダーと競合しています。	要求の詳細をログに記録してください。要求を調べて、このドキュメントと比較してください。
401 Unauthorized	クラウドサービスが有効な認証チケットを提示しませんでした。OAuth チケットが無効である可能性があります。	アクセストークン要求を使ってクラウドサービスを認証し、有効なアクセストークンを要求してください。
403 Forbidden	クラウドサービスは、認証はされますが、通知をこの URI に送ることを承認されません。	要求で提供されたアクセストークンが、チャネルの URI を要求したアプリの資格情報と一致していません。アプリのマニフェストにあるパッケージ名が、ダッシュボードのアプリに提供されているクラウドサービスの資格情報と一致することを確認してください。
404 Not Found	チャネルの URI が有効でないか、WNS に認識されません。	要求の詳細をログに記録してください。このチャネルにはこれ以上通知を送信しないでください。このアドレスへの通知は失敗します。
405 Method Not Allowed	無効なメソッド (GET, CREATE); POST (Windows or Windows Phone) または DELETE (Windows Phone only) のみ使用できます。	要求の詳細をログに記録してください。HTTP POST の使用に切り替えてください。
406 Not Acceptable	クラウドサービスのスロットル制限を超えました。	要求の詳細をログに記録してください。通知の送信速度を下げてください。
410 Gone	チャネルの有効期限が切れました。	要求の詳細をログに記録してください。このチャネルにはこれ以上通知を送信しないでください。アプリに新しいチャネルの URI を要求させてください。
413 Request Entity Too Large	通知のペイロードが、5000 バイトのサイズ制限を超えています。	要求の詳細をログに記録してください。ペイロードを調べて、サイズ制限内に収まるようにしてください。
500 Internal Server Error	内部エラーが原因で通知の配信が失敗しました。	要求の詳細をログに記録してください。開発者フォーラムを通じてこの問題をレポートしてください。
503 Service Unavailable	現在サーバーを利用できません。	要求の詳細をログに記録してください。開発者フォーラムを通じてこの問題をレポートしてください。

特定の応答コードに関するトラブルシューティングについて詳しくは、「タイル、トースト、バッジ通知のトラブルシューティング」をご覧ください。「COM Error Codes (WPN, MBN, P2P, Bluetooth)」もご覧ください。

サポートされない HTTP 機能

WNS Web インターフェイスでは、HTTP 1.1 はサポートされますが、以下の機能はサポートされません。

チャンキング
パイプライン化 (POST はべき等ではありません)
Expect-100 は、サポートされますが、通知の送信時に遅延が発生するため、開発者は無効にする必要があります。

プッシュ通知サービスの要求ヘッダーと応答ヘッダー (Windows ランタイムアプリ)

アクセストークンの要求と受信

アクセストークン要求

アクセストークン要求パラメーター

アクセストークン応答

アクセストークン応答パラメーター

応答コード

例

通知要求の送信と応答の受信

通知要求を送信する

要求パラメーター

重要な注意

承認

X-WNS-Type

X-WNS-Cache-Policy

X-WNS-RequestForStatus

X-WNS-Tag

X-WNS-TTL

X-WNS-SuppressPopup

X-WNS-Group

X-WNS-Match

通知応答を送信する

応答パラメーター

X-WNS-Debug-Trace

X-WNS-DeviceConnectionStatus

X-WNS-Error-Description

X-WNS-Msg-ID

X-WNS-Status

応答コード

サポートされない HTTP 機能

関連トピック

その他のリソース

プッシュ通知サービスの要求ヘッダーと応答ヘッダー (Windows ランタイム アプリ)

アクセス トークンの要求と受信

アクセス トークン要求

アクセス トークン要求パラメーター

アクセス トークン応答

アクセス トークン応答パラメーター

応答コード

例

通知要求の送信と応答の受信

通知要求を送信する

要求パラメーター

重要な注意

承認

X-WNS-Type

X-WNS-Cache-Policy

X-WNS-RequestForStatus

X-WNS-Tag

X-WNS-TTL

X-WNS-SuppressPopup

X-WNS-Group

X-WNS-Match

通知応答を送信する

応答パラメーター

X-WNS-Debug-Trace

X-WNS-DeviceConnectionStatus

X-WNS-Error-Description

X-WNS-Msg-ID

X-WNS-Status

応答コード

サポートされない HTTP 機能

関連トピック

その他のリソース

プッシュ通知サービスの要求ヘッダーと応答ヘッダー (Windows ランタイムアプリ)

アクセストークンの要求と受信

アクセストークン要求

アクセストークン要求パラメーター

アクセストークン応答

アクセストークン応答パラメーター