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

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

プッシュ通知と WNS の概念、要件、および操作の概念については、 Windows プッシュ通知サービス ( WNS) の概要を参照してください。

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

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

アクセス トークン要求

クラウド サービスを認証し、その代わりにアクセス トークンを取得するために、HTTP 要求が WNS に送信されます。 要求は、Secure Sockets Layer (SSL) を使用して https://login.live.com/accesstoken.srf に発行されます。

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

クラウド サービスは、"application/x-www-form-urlencoded" 形式を使用して、HTTP 要求本文でこれらの必須パラメーターを送信します。 すべてのパラメーターが URL エンコードされていることを確認する必要があります。

パラメーター	必須	説明
grant_type（グラントタイプ）	真実	client_credentialsに設定する必要があります。
クライアントID	真実	アプリを Microsoft Store に登録したときに割り当てられたクラウド サービスのパッケージ セキュリティ識別子 (SID)。
クライアントシークレット	真実	アプリを Microsoft Store に登録したときに割り当てられたクラウド サービスの秘密鍵。
範囲	真実	notify.windows.com に設定されている必要があります。

アクセストークン応答

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

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

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

パラメーター	必須	説明
アクセス トークン	真実	クラウド サービスが通知を送信するときに使用するアクセス トークン。
トークンタイプ	偽	常に bearerとして返されます。

応答コード

HTTP 応答コード	説明
200 OK（正常に処理されました）	要求は成功しました。
400 無効な要求	認証に失敗しました。 応答パラメーターについては、 OAuth ドラフト のコメント要求 (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",
     "expires_in": 86400
 }

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

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

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

通知要求を送信する

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

さらに、ここで一覧表示されているカスタム要求ヘッダーは、通知要求で使用できます。 一部のヘッダーは必須ですが、他のヘッダーは省略可能です。

要求パラメーター

ヘッダー名	必須	説明
認証	真実	通知要求の認証に使用される標準の HTTP 承認ヘッダー。 クラウド サービスは、このヘッダーにアクセス トークンを提供します。
コンテンツタイプ	真実	標準 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	偽	有効期間 (TTL) を指定する整数値 (秒単位)。
MS-CV	偽	要求に使用される相関ベクトル値。

重要な注意事項

• Content-Length と Content-Type は、他の標準ヘッダーが要求に含まれているかどうかに関係なく、クライアントに配信される通知に含まれる唯一の標準 HTTP ヘッダーです。
• 他のすべての標準 HTTP ヘッダーは無視されるか、機能がサポートされていない場合はエラーを返します。
• 2023 年 2 月以降、デバイスがオフラインの場合、WNS はタイル通知を 1 つだけキャッシュします。

認証

認証ヘッダーは、ベアラー トークンの OAuth 2.0 認証方法に従って、呼び出し元の資格情報 指定するために使用されます。

構文は、文字列リテラル "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 /タイル	タイルのコンテンツを更新するための通知。 通知要求に含まれる Content-Type ヘッダーは、 text/xmlに設定する必要があります。
WNS /トースト	クライアントに乾杯の通知を送信する。 通知要求に含まれる Content-Type ヘッダーは、 text/xmlに設定する必要があります。
WNS/ロー	カスタム ペイロードを含め、アプリに直接配信される通知。 通知要求に含まれる Content-Type ヘッダーは、 application/octet-streamに設定する必要があります。

X-WNS-Cache-Policy

通知ターゲット デバイスがオフラインの場合、WNS はチャネル URI ごとに 1 つのバッジ、1 つのタイル、および 1 つのトースト通知をキャッシュします。 既定では、生通知はキャッシュされませんが、生通知のキャッシュが有効になっている場合は、1 つの生通知がキャッシュされます。 項目はキャッシュに無期限に保持されず、妥当な期間が経過すると削除されます。 それ以外の場合、キャッシュされたコンテンツは、デバイスが次にオンラインになったときに配信されます。

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

価値	説明
キャッシュ	既定値。 ユーザーがオフラインの場合、通知はキャッシュされます。 これは、タイル通知とバッジ通知の既定の設定です。
キャッシュなし	ユーザーがオフラインの場合、通知はキャッシュされません。 これは、未加工通知の既定の設定です。

X-WNS-RequestForStatus

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

    X-WNS-RequestForStatus: true | false

価値	説明
ほんとう	応答でデバイスの状態と通知の状態を返します。
偽り	既定値。 デバイスの状態と通知の状態を返さないでください。

X-WNS-Tag

通知にタグ ラベルを割り当てます。 タグは、アプリが通知の循環を選択したときに、通知キュー内のタイルの置換ポリシーで使用されます。 このタグを持つ通知が既にキューに存在する場合は、同じタグを持つ新しい通知が発生します。

注

このヘッダーは省略可能であり、タイル通知を送信する場合にのみ使用されます。

    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 |偽

価値	説明
ほんとう	トースト通知をアクションセンターに直接送信します。トーストUIを表示させないでください。
偽り	既定値。 トースト UI を表示し、アクション センターに通知を追加します。

X-WNS-Group

注

Windows Phone ストア アプリのアクション センターでは、異なるグループに属しているとラベル付けされている場合にのみ、同じタグを持つ複数のトースト通知を表示できます。 たとえば、レシピブックアプリを考えてみましょう。 各レシピはタグによって識別されます。 そのレシピに対するコメントを含むトーストには、レシピのタグが付けられますが、コメント グループ ラベルが含まれます。 そのレシピの評価を含むトーストには、そのレシピのタグが再び含まれますが、評価グループ ラベルが付けられます。 これらの異なるグループ ラベルを使用すると、両方のトースト通知をアクション センターに一度に表示できます。 このヘッダーは省略可能です。

X-WNSグループ: <string value>

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

X-WNS-Match

注

特定のトースト、一連のトースト (タグまたはグループによる)、または Windows Phone ストア アプリのアクション センターからすべてのトーストを削除するために、HTTP DELETE メソッドと共に使用されます。 このヘッダーでは、グループ、タグ、またはその両方を指定できます。 このヘッダーは、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;全て

価値	説明
タイプ:WNS / TOAST;グループ=<string value>;タグ=<string value>	指定したタグとグループの両方でラベル付けされた 1 つの通知を削除します。
タイプ:WNS / TOAST;グループ=<string value>	指定したグループでラベル付けされたすべての通知を削除します。
タイプ:WNS / TOAST;タグ=<string value>	指定したタグでラベル付けされたすべての通知を削除します。
type:wns/toast;すべての	アクション センターからアプリのすべての通知をクリアします。

通知応答を送信する

WNS は、通知要求を処理した後、応答として HTTP メッセージを送信します。 このセクションでは、その応答で見つかるパラメーターとヘッダーについて説明します。

応答パラメーター

ヘッダー名	必須	説明
X-WNS-Debug-Trace	偽	問題を報告する際の問題のトラブルシューティングに役立つ、ログに記録する必要があるデバッグ情報。
X-WNS-DeviceConnectionStatus	偽	デバイスの状態。X-WNS-RequestForStatus ヘッダーを介して通知要求で要求された場合にのみ返されます。
X-WNS-Error-Description	偽	デバッグを支援するためにログに記録する必要がある、人間が判読できるエラー文字列。
X-WNS-Msg-ID	偽	デバッグ目的で使用される通知の一意識別子。 問題を報告するときは、トラブルシューティングに役立つ情報をログに記録する必要があります。
X-WNS-Status	偽	WNS が正常に通知を受信して処理したかどうかを示します。 問題を報告するときは、トラブルシューティングに役立つ情報をログに記録する必要があります。
MS-CV	偽	問題を報告する際の問題のトラブルシューティングに役立つ、ログに記録する必要があるデバッグ情報。

X-WNS-Debug-Trace

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

X-WNS-デバッグ-トレース: <string value>

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

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus: 接続中 | 切断 | 一時的に切断

価値	説明
つながった	デバイスはオンラインで、WNS に接続されています。
切断された	デバイスはオフラインであり、WNS に接続されていません。
tempconnected (非推奨)	デバイスが WNS への接続を一時的に失いました。たとえば、3G 接続が切断された場合や、ノート PC のワイヤレス スイッチがスローされた場合などです。 通知クライアント プラットフォームでは、意図的な切断ではなく、一時的な中断と見なされます。

X-WNS-Error-Description

このヘッダーは、デバッグに役立つログに記録する必要がある、人間が判読できるエラー文字列を提供します。

X-WNS-エラー-説明: <string value>

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

X-WNS-Msg-ID

このヘッダーは、呼び出し元に通知の識別子を提供するために使用されます。 問題のデバッグに役立つよう、このヘッダーをログに記録することをお勧めします。 このヘッダーは、問題を WNS に報告するときに、X-WNS-Debug-Trace および MS-CV と共に必要です。

X-WNS-メッセージ-ID: <string value>

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

X-WNS-Status

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

X-WNS-Status: 受信済み | 破棄済み | チャンネル制限中

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

MS-CV

このヘッダーは、主にデバッグに使用される要求に関連する相関ベクトルを提供します。 要求の一部として CV が指定されている場合、WNS はこの値を使用します。それ以外の場合、WNS は CV を生成して応答します。 このヘッダーは、問題を WNS に報告するときに、X-WNS-Debug-Trace および X-WNS-Msg-ID ヘッダーと共に必要です。

Von Bedeutung

独自の CV を提供している場合は、プッシュ通知要求ごとに新しい CV を生成してください。

MS-CVの <string value>

価値	説明
文字列値	相関ベクトル標準に従う

応答コード

各 HTTP メッセージには、これらの応答コードのいずれかが含まれています。 WNS では、開発者がデバッグで使用するために応答コードをログに記録することをお勧めします。 開発者が WNS に問題を報告するときは、応答コードとヘッダー情報を提供する必要があります。

HTTP 応答コード	説明	推奨されるアクション
200 OK（正常に処理されました）	通知は WNS によって受け入れられました。	必要ありません。
400 無効な要求	1 つ以上のヘッダーが正しく指定されていないか、別のヘッダーと競合しています。	要求の詳細をログに記録します。 要求を調べて、このドキュメントと比較します。
401 権限がありません	クラウド サービスが有効な認証チケットを提示しませんでした。 OAuth チケットが無効である可能性があります。	アクセス トークン要求を使用してクラウド サービスを認証して、有効なアクセス トークンを要求します。
403 許可されていません	クラウド サービスは、認証されているにもかかわらず、この URI に通知を送信する権限がありません。	要求で指定されたアクセス トークンが、チャネル URI を要求したアプリの資格情報と一致しません。 アプリのマニフェスト内のパッケージ名が、ダッシュボードでアプリに与えられたクラウド サービスの資格情報と一致していることを確認します。
404 見つかりません	チャネル URI が無効であるか、WNS によって認識されません。	要求の詳細をログに記録します。 このチャネルにそれ以上の通知を送信しないでください。このアドレスへの通知は失敗します。
405 メソッドが許可されていません	無効なメソッド (GET、CREATE);POST (Windows または Windows Phone) または DELETE (Windows Phone のみ) のみが許可されます。	要求の詳細をログに記録します。 HTTP POST の使用に切り替えます。
406 受け入れ不可	クラウド サービスがスロットル制限を超えました。	応答の Retry-After ヘッダー値の後に要求を送信してください
410 Gone（リソースが削除されました）	チャネルの有効期限が切れています。	要求の詳細をログに記録します。 このチャネルにそれ以上の通知を送信しないでください。 アプリで新しいチャネル URI を要求します。
410 ドメインがブロックされました	送信ドメインは WNS によってブロックされています。	このチャネルにそれ以上の通知を送信しないでください。 送信ドメインは、プッシュ通知を悪用するために WNS によってブロックされています。
413 リクエストエンティティが大きすぎます	通知ペイロードが 5,000 バイトのサイズ制限を超えています。	要求の詳細をログに記録します。 ペイロードを調べて、サイズの制限内にあることを確認します。
500 内部サーバー エラー	内部エラーにより、通知の配信が失敗しました。	要求の詳細をログに記録します。 開発者フォーラムを通じてこの問題を報告します。
503 サービスを利用できない	サーバーは現在使用できません。	要求の詳細をログに記録します。 開発者フォーラムを通じてこの問題を報告します。 Retry-After ヘッダーが観察された場合は、応答の Retry-After ヘッダー値の後に要求を送信してください。

サポートされていない HTTP 機能

WNS Web インターフェイスは HTTP 1.1 をサポートしていますが、次の機能はサポートしていません。

• チャンキング
• パイプライン処理 (POST はべき等ではありません)
• サポートされていますが、開発者は Expect-100 を無効にする必要があります。これにより、通知の送信時に待機時間が発生します。