言語: HTML | XAML

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

ここでは、プッシュ通知を送るために必要なサービス間 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 要求に含まれるヘッダーと、応答に含まれるヘッダーについて説明します。

通知要求を送信する

通知要求を送るときに、呼び出し元のアプリは、チャネルの 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.0bearer トークンの場合の承認方法に従って、承認ヘッダーを使って呼び出し元の資格情報を指定します。

構文は、文字列リテラル "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 Request1 つ以上のヘッダーが、誤って指定されていたか、別のヘッダーと競合しています。要求の詳細をログに記録してください。要求を調べて、このドキュメントと比較してください。
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 プッシュ通知サービス (WNS) に対して認証する方法
通知チャネルを要求、作成、保存する方法
プッシュ通知と定期的な通知のサンプル
WNS の概要

 

 

表示:
© 2015 Microsoft