推播通知服務要求和回應標頭 (Windows 執行時期應用程式)
本主題說明傳送推播通知所需的服務對服務 Web API 和通訊協定。
請參閱 Windows 推播通知服務 (WNS)，以了解推播通知和 WNS 概念、需求和作業的概念討論。
要求和接收存取權杖
本節說明透過 WNS 進行驗證時所涉及的要求和回應參數。
存取權杖要求
HTTP 要求會傳送至 WNS 以驗證雲端服務，並擷取傳回的存取權杖。 要求是使用安全通訊端層 (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 會回應適當的 HTTP 錯誤碼，如 OAuth 2.0 通訊協定 Draft 中所述。
存取權杖回應參數
如果雲端服務驗證成功，則會在 HTTP 回應中傳回存取權杖。 此存取權杖可在通知要求中使用，直到過期為止。 HTTP 回應會使用「application/json」媒體類型。
| 參數 | 必要 | 描述 |
|---|---|---|
| access_token | TRUE | 雲端服務傳送通知時將使用的存取權杖。 |
| token_type | FALSE | 一律做為 bearer 傳回。 |
回應碼
| HTTP 回應碼 | 描述 |
|---|---|
| 200 OK | 要求成功。 |
| 400 不正確的要求 | 驗證失敗。 請參閱 OAuth Draft 要求建議 (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 要求，並定址至統一資源識別元 (URI) 通道。 “Content-Length” 是要求中必須指定的標準 HTTP 標頭。 所有其他標準標頭不是選用，就是不支援。
此外，此處列出的自訂要求標頭可以在通知要求中使用。 有些標頭為必要，有些則是選用。
要求參數
| 標頭名稱 | 必要 | 描述 |
|---|---|---|
| 授權 | 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 | 以秒數表示的整數值，用來指定存留時間 (TTL)。 |
| MS-CV | FALSE | 用於要求的相互關聯向量值。 |
重要注意
- Content-Length 和 Content-Type 是唯一包含在傳遞至用戶端的通知中的標準 HTTP 標頭，無論要求中是否包含其他標準標頭。
- 如果不支援此功能，則會忽略所有其他標準 HTTP 標頭，或傳回錯誤。
- 從 2023 年 2 月開始，當裝置離線時，WNS 只會快取一則磚通知。
授權
授權標頭用來指定呼叫方的認證，它會遵循 OAuth 2.0 授權方法來處理持有人權杖。
語法包含字串常值「Bearer」，後面接著一個空格，再接著您的存取權杖。 此存取權杖是藉由發出上述存取權杖要求來擷取。 這個存取權杖可在後續通知要求上使用，直到過期為止。
此標頭為必要。
Authorization: Bearer <access-token>
X-WNS-Type
這些是 WNS 支援的通知類型。 此標頭會指出通知的類型，以及 WNS 處理它的方式。 通知到達用戶端後，會根據這個指定的類型驗證實際的承載。 此標頭為必要。
X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
| 值 | Description |
|---|---|
| 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 快取一則徽章通知、一則磚通知和一則快顯通知。 根據預設不會快取原始通知，但如果原始通知快取已啟用，則會快取一則原始通知。 項目不會無限期保留在快取中，會在一段合理的時間後捨棄。 否則，當裝置下一次上線時，就會傳遞快取的內容。
X-WNS-Cache-Policy: cache | no-cache
| 值 | Description |
|---|---|
| 快取 | 預設。 如果使用者離線，將會快取通知。 這是磚和徽章通知的預設設定。 |
| 無快取 | 如果使用者離線，將不會快取通知。 這是原始通知的預設設定。 |
X-WNS-RequestForStatus
指定回應是否應該包含裝置狀態和 WNS 連線狀態。 這是選擇性標頭。
X-WNS-RequestForStatus: true | false
| 值 | 描述 |
|---|---|
| true | 在回應中傳回裝置狀態和通知狀態。 |
| false | 預設。 不傳回裝置狀態和通知狀態。 |
X-WNS-Tag
將 tag 標籤指派給通知。 當應用程式選擇加入通知循環時，標籤會在通知佇列中磚的取代原則中使用。 如果佇列中已有具有此標籤的通知，則具有相同標籤的新通知會將它取代。
注意
這是選用標頭，只有在傳送磚通知時才會使用。
X-WNS-Tag: <string value>
| 值 | Description |
|---|---|
| 字串值 | 不超過 16 個字元的英數字串。 |
X-WNS-TTL
指定通知的 TTL (到期時間)。 通常並不需要此項，但如果您希望確保通知顯示的時間不會晚於特定時間，則可以使用。 TTL 是以秒為單位指定，且相對於 WNS 接收要求的時間。 指定 TTL 時，裝置不會在該時間之後顯示通知。 請注意，如果 TTL 太短，可能會導致完全不會顯示通知。 一般而言，到期時間至少會以分鐘為單位來衡量。
這是選擇性標頭。 如果未指定任何值，則通知不會過期，而且會依照標準通知取代結構描述加以取代。
X-WNS-TTL：<integer value>
| 值 | Description |
|---|---|
| 整數值 | WNS 收到要求之後，以秒為單位的通知存留期間。 |
X-WNS-SuppressPopup
注意
針對 Windows Phone Store 應用程式，您可以選擇隱藏快顯通知的 UI，而改為將通知直接傳送至重要訊息中心。 這樣做可讓您的通知以無訊息方式傳遞，對於較不急迫的通知來說可能是優先選擇。 這是選用標頭，僅在 Windows Phone 通道上使用。 如果您在 Windows 通道中包含此標頭，將會捨棄您的通知，而且您會收到來自 WNS 的錯誤回應。
X-WNS-SuppressPopup：true | false
| 值 | 描述 |
|---|---|
| true | 將快顯通知直接傳送至重要訊息中心；不引發快顯 UI。 |
| false | 預設。 引發快顯 UI，以及將通知新增至重要訊息中心。 |
X-WNS-Group
注意
Windows Phone Store 應用程式的重要訊息中心只能顯示擁有相同標籤的多則快顯通知 (如果這些通知標記為屬於不同群組)。 例如，請參考食譜應用程式。 每一個食譜都加上標籤來識別。 若快顯包含對該食譜的評論，則會具有該食譜的標籤，但會是評論群組標籤。 若快顯包含對該食譜的評等，則會再次具有該食譜的標籤，但會有評等群組標籤。 這些不同的群組標籤會讓這兩則快顯通知一起顯示在重要訊息中心內。 這是選擇性標頭。
X-WNS-Group：<string value>
| 值 | Description |
|---|---|
| 字串值 | 不超過 16 個字元的英數字串。 |
X-WNS-Match
注意
搭配 HTTP DELETE 方法可用來從 Windows Phone Store 應用程式的重要訊息中心移除特定快顯、一組快顯 (依標籤或群組) 或所有快顯。 此標頭可以指定群組、標籤，或兩者都指定。 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
| 值 | Description |
|---|---|
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>
| 值 | Description |
|---|---|
| 字串值 | 英數字串。 |
X-WNS-DeviceConnectionStatus
如果在通知要求的 X-WNS-RequestForStatus 標頭中提出要求，則此標頭會將裝置狀態傳回至呼叫端應用程式。
X-WNS-DeviceConnectionStatus：connected | disconnected | tempdisconnected
| 值 | Description |
|---|---|
| connected | 裝置處於上線狀態並已連線至 WNS。 |
| disconnected | 裝置處於離線狀態且未連線至 WNS。 |
| tempconnected (已取代) | 裝置暫時中斷與 WNS 的連線，例如，當 3G 連線中斷或膝上型電腦上的無線交換器擲回時。 通知用戶端平台會將它視為暫時中斷，而不是刻意中斷連線。 |
X-WNS-Error-Description
此標頭提供人類可閱讀的錯誤字串，應記錄以協助進行偵錯。
X-WNS-Error-Description：<string value>
| 值 | Description |
|---|---|
| 字串值 | 英數字串。 |
X-WNS-Msg-ID
此標頭用來為呼叫端提供通知的識別碼。 建議您記錄此標頭，以協助偵錯問題。 向 WNS 回報問題時，需有此標頭與 X-WNS-Debug-Trace 和 MS-CV。
X-WNS-Msg-ID：<string value>
| 值 | Description |
|---|---|
| 字串值 | 不超過 16 個字元的英數字串。 |
X-WNS-Status
此標頭說明 WNS 如何處理通知要求。 可以使用此標頭，而不要將回應碼解譯為成功或失敗。
X-WNS-Status：received | dropped | channelthrottled
| 值 | Description |
|---|---|
| 已接收 | WNS 已收到並處理通知。 注意：不保證裝置會收到通知。 |
| 已捨棄 | 因為發生錯誤或用戶端已明確拒絕這些通知，而明確捨棄通知。 如果裝置離線，則也會捨棄快顯通知。 |
| channelthrottled | 因為應用程式伺服器超過此特定通道的速率限制，所以已捨棄通知。 |
MS-CV
此標頭提供與主要用於偵錯的要求相關的相互關聯向量。 如果隨要求提供 CV，則 WNS 會使用此值，否則 WNS 將產生並回應 CV。 向 WNS 回報問題時，需有此標頭與 X-WNS-Debug-Trace 和 X-WNS-Msg-ID 標頭。
重要
如果您要提供自己的 CV，請針對每則推播通知要求產生新的 CV。
MS-CV：<string value>
| 值 | Description |
|---|---|
| 字串值 | 遵循相互關聯向量標準 |
回應碼
每個 HTTP 訊息都包含其中一個回應碼。 WNS 建議開發人員記錄回應碼，以用於偵錯。 當開發人員向 WNS 回報問題時，必須提供回應碼和標頭資訊。
| HTTP 回應碼 | 描述 | 建議的動作 |
|---|---|---|
| 200 OK | WNS 已接受通知。 | 無。 |
| 400 不正確的要求 | 一或多個標頭未正確指定，或與其他標頭衝突。 | 請記錄您的請求詳細資訊。 檢查您的要求，並對照此文件。 |
| 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 已封鎖網域 | WNS 已封鎖傳送網域。 | 不要進一步傳送通知至此通道。 因濫用推播通知，WNS 已封鎖傳送網域。 |
| 413 要求實體太大 | 通知承載超過 5000 個位元組大小限制。 | 請記錄您的請求詳細資訊。 檢查承載，確認其符合大小限制。 |
| 500 內部伺服器錯誤 | 內部失敗導致通知傳遞失敗。 | 記錄要求的詳細資料。 透過開發人員論壇回報此問題。 |
| 503 服務無法使用 | 伺服器目前無法使用。 | 記錄要求的詳細資料。 透過開發人員論壇回報此問題。 如果遵循 Retry-After 標頭，請在回應中 Retry-After 標頭值的後面傳送您的要求。 |
不支援的 HTTP 功能
WNS Web 介面支援 HTTP 1.1，但不支援下列功能：
- 區塊處理
- 管線 (POST 不是等冪)
- 雖然支援 Expect-100，但開發人員應將它停用，因為這樣會在傳送通知時造成延遲。
