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

[アーティクル]
05/03/2024

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

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

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

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

Access token request (アクセストークン要求)

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

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

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

パラメーター	必須	説明
grant_type	TRUE	`client_credentials` に設定する必要があります。
client_id	TRUE	Microsoft Store にアプリを登録したときに割り当てられた、クラウドサービスのパッケージセキュリティ識別子 (SID)。
client_secret	TRUE	Microsoft Store にアプリを登録したときに割り当てられたクラウドサービスの秘密キー。
scope	TRUE	`notify.windows.com` に設定されている必要があります。

アクセストークン応答

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

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

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

パラメーター	必須	説明
access_token	TRUE	クラウドサービスで通知を送信するときに使用されるアクセストークン。
token_type	FALSE	常に `bearer` として返されます。

応答コード

HTTP 応答コード	説明
200 OK	要求は成功しました。
400 要求が正しくありません	認証に失敗しました。応答パラメーターについては、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",
     "expires_in": 86400
 }

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

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

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

通知要求を送信する

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

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

要求パラメーター

ヘッダー名	必須	説明
Authorization	TRUE	通知要求の認証に使用される標準の HTTP 承認ヘッダー。クラウドサービスにより、このヘッダーでアクセストークンが提供されます。
コンテンツタイプ	TRUE	標準の HTTP 承認ヘッダー。トースト、タイル、バッジ通知については、このヘッダーを `text/xml` に設定する必要があります。直接通知については、このヘッダーを `application/octet-stream` に設定する必要があります。
Content-Length	TRUE	要求ペイロードのサイズを示す標準の HTTP 承認ヘッダー。
X-WNS-Type	TRUE	ペイロード内の通知の種類 (タイル、トースト、バッジ、直接) を定義します。
X-WNS-Cache-Policy	FALSE	通知キャッシュを有効または無効にします。このヘッダーは、タイル、バッジ、および直接通知にのみ適用されます。
X-WNS-RequestForStatus	FALSE	通知応答でデバイスの状態と WNS 接続状態を要求します。
X-WNS-Tag	FALSE	通知キューをサポートするタイルに使用される、識別ラベル付きの通知を提供するために使用される文字列。このヘッダーはタイル通知にのみ適用されます。
X-WNS-TTL	FALSE	Time to Live (TTL) を指定する、秒単位で表される整数値。
MS-CV	FALSE	要求に使用される相関ベクトル値。

重要

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/tile	タイルコンテンツを更新する通知。通知要求に含まれる Content-Type ヘッダーは `text/xml` に設定する必要があります。
wns/toast	クライアントでトーストを発生させる通知。通知要求に含まれる Content-Type ヘッダーは `text/xml` に設定する必要があります。
wns/raw	カスタムペイロードを含むことができ、アプリに直接配信される通知。通知要求に含まれる Content-Type ヘッダーは `application/octet-stream` に設定する必要があります。

X-WNS-Cache-Policy

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

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

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

X-WNS-RequestForStatus

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

    X-WNS-RequestForStatus: true | false

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

X-WNS-Tag

通知にタグラベルを割り当てます。タグは、アプリによって通知サイクリングが選択されたときに、通知キューのタイルの置換ポリシーで使用されます。このタグの付いた通知が既にキューに存在する場合は、同じタグの新しい通知が代わりに使用されます。

Note

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

    X-WNS-Tag: <string value>

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

X-WNS-TTL

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

このヘッダーは省略可能です。値が指定されていない場合、通知は期限切れにならず、通常の通知置換スキーム下で置き換えられます。

X-WNS-TTL: <integer value>

値	説明
整数値	WNS で要求が受信された後の通知の存続期間 (秒単位)。

X-WNS-SuppressPopup

Note

Windows Phone ストアアプリの場合、トースト通知の UI を非表示にするオプションがあり、代わりにアクションセンターに通知を直接送信します。これにより、通知をサイレントに配信することができます。これは、緊急度の低い通知に適している可能性のあるオプションです。このヘッダーは省略可能であり、Windows Phone チャネルでのみ使用されます。このヘッダーを Windows チャネルに含めると、通知が削除され、WNS からのエラー応答を受信することになります。

X-WNS-SuppressPopup: true | false

値	説明
true	トースト通知をアクションセンターに直接送信します。トースト UI は表示されません。
false	既定値。アクションセンターに通知を追加するだけでなく、トースト UI を表示します。

X-WNS-Group

Note

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

X-WNS-Group: <string value>

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

X-WNS-Match

Note

HTTP DELETE メソッドと共に使用して、特定のトースト、一連のトースト (タグまたはグループ別)、またはすべてのトーストを Windows Phone ストアアプリのアクションセンターから削除します。このヘッダーでは、グループまたはタグ、あるいはその両方を指定できます。このヘッダーは 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=`<string value>`;tag=`<string value>`	指定されたタグとグループの両方でラベル付けされている単一の通知を削除します。
type:wns/toast;group=`<string value>`	指定されたグループでラベル付けされているすべての通知を削除します。
type:wns/toast;tag=`<string value>`	指定されたタグでラベル付けされたすべての通知を削除します。
type:wns/toast;all	アクションセンターからアプリの通知をすべてクリアします。

通知応答を送信する

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

応答パラメーター

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

X-WNS-Debug-Trace

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

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

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

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

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

X-WNS-Error-Description

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

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

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

X-WNS-Msg-ID

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

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

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

X-WNS-Status

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

X-WNS-Status: received | dropped | channelthrottled

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

MS-CV

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

重要

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

MS-CV: <string value>

値	説明
文字列値	相関ベクトルの標準に従います

応答コード

各 HTTP メッセージには、これらの応答コードの 1 つが含まれています。 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 削除	チャネルの有効期限が切れています。	要求の詳細をログに記録します。このチャネルにそれ以上通知を送信しないでください。アプリで新しいチャネル URI を要求するようにします。
410 Domain Blocked	送信ドメインが WNS によってブロックされました。	このチャネルにそれ以上通知を送信しないでください。送信ドメインは、プッシュ通知を悪用するため WNS によってブロックされています。
413 要求のエンティティが大きすぎます	通知ペイロードが 5,000 バイトのサイズ制限を超えています。	要求の詳細をログに記録します。ペイロードを調べ、サイズの制限内にあることを確かめます。
500 内部サーバーエラー	内部エラーにより、通知の配信が失敗しました。	要求の詳細をログに記録します。開発者フォーラムを通じて、この問題を報告してください。
503 サービスは使用できません	サーバーは現在使用できません。	要求の詳細をログに記録します。開発者フォーラムを通じて、この問題を報告してください。 Retry-After ヘッダーが確認された場合は、応答で Retry-After ヘッダー値の後に要求を送信してください。

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

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

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

次の方法で共有

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

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

Access token request (アクセストークン要求)

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

アクセストークン応答

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

応答コード

例

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

通知要求を送信する

要求パラメーター

重要

認可

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

MS-CV

応答コード

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

その他のリソース

次の方法で共有

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

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

Access token request (アクセス トークン要求)

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

アクセス トークン応答

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

応答コード

例

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

通知要求を送信する

要求パラメーター

重要

認可

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

MS-CV

応答コード

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

その他のリソース

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

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

Access token request (アクセストークン要求)

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

アクセストークン応答

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