推播通知服務請求和回應標頭 （Windows 執行環境應用程式）

本主題描述傳送推播通知所需的服務對服務Web API和通訊協定。

如需推播通知和 WNS 概念、需求和作業的概念性討論，請參閱 Windows 推播通知服務 （WNS） 概觀。

要求和接收存取令牌

本節說明向 WNS 驗證時所涉及的要求和響應參數。

存取令牌要求

HTTP 要求會傳送至 WNS 以驗證雲端服務，並擷取傳回的存取令牌。 要求會使用安全套接字層 （SSL） 發出給 https://login.live.com/accesstoken.srf。

存取令牌要求參數

雲端服務會使用 「application/x-www-form-urlencoded」 格式，在 HTTP 要求本文中提交這些必要參數。 您必須確定所有參數都經過 URL 編碼。

存取令牌回應

WNS 會驗證雲端服務，如果成功，則會以 「200 OK」 回應，包括存取令牌。 否則，WNS 會回應適當的 HTTP 錯誤碼，如 OAuth 2.0 通訊協定草稿中所述。

存取令牌響應參數

如果雲端服務成功驗證，則會在 HTTP 回應中傳回存取令牌。 此存取令牌可用於通知要求，直到到期為止。 HTTP 回應會使用 「application/json」 媒體類型。

回應碼

Example

以下顯示成功的驗證回應範例：

 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 標頭。 所有其他標準標頭皆為選擇性或不受支援。

此外，此處所列的自定義要求標頭可用於通知要求。 有些標頭是必要的，有些則為選擇性標頭。

要求參數

重要注意

• Content-Length 和 Content-Type 是唯一包含在傳送給用戶端之通知中的標準 HTTP 標頭，不論要求中是否包含其他標準標頭。
• 如果不支援此功能，則會忽略所有其他標準 HTTP 標頭，或傳回錯誤。
• 從 2023 年 2 月開始，當裝置處於離線狀態時，WNS 只會快取一個動態磚通知。

Authorization

授權標頭是用來指定呼叫端的認證，方法是遵循 持有人 令牌的 OAuth 2.0 授權方法。

語法由字串常值「Bearer」加上一個空格，然後是您的存取令牌組成。 此存取令牌是透過發出上述的存取令牌請求來取得的。 相同的存取令牌可以在後續的通知要求上使用，直到到期為止。

此標頭是必要的。

Authorization: Bearer <access-token>

X-WNS-Type

這些是 WNS 支援的通知類型。 此標頭會指出通知的類型，以及 WNS 應該如何處理它。 通知到達客戶端之後，會根據這個指定的類型驗證實際的承載。 此標頭是必要的。

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

X-WNS-Cache-Policy

當通知目標裝置離線時，WNS 會針對每個通道 URI 快取一個徽章、一個圖磚和一個即時通知。 根據預設，不會快取原始通知，但如果啟用原始通知快取，則會快取一個原始通知。 項目不會無限期地保留在快取中，而且會在一段合理的時間之後移除。 否則，當裝置下一次上線時，就會傳遞快取的內容。

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

X-WNS-RequestForStatus

指定回應是否應該包含裝置狀態和 WNS 連線狀態。 此標頭是選擇性的。

    X-WNS-RequestForStatus: true | false

X-WNS-Tag

將 標籤 標籤指派給通知。 當應用程式選擇通知循環時，標籤在通知佇列中用於取代磚的策略。 如果佇列中已經有此標記的通知，則具有相同標籤的新通知就會發生。

    X-WNS-Tag: <string value>

X-WNS-TTL

指定通知的 TTL （到期時間）。 這通常不需要，但如果您想要確保您的通知不會晚於特定時間顯示，則可以使用。 TTL 是以秒為單位指定，且相對於 WNS 接收要求的時間。 指定 TTL 時，裝置不會在該時間之後顯示通知。 請注意，如果 TTL 太短，這可能會導致完全不會顯示通知。 一般而言，到期時間至少會以分鐘為單位來測量。

此標頭是選擇性的。 如果未指定任何值，則通知不會過期，而且會在一般通知取代配置下取代。

X-WNS-TTL：<integer value>

X-WNS-SuppressPopup

X-WNS-SuppressPopup： true | false

X-WNS-Group

X-WNS-Group：<string value>

X-WNS-Match

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

發送通知回應

WNS 處理通知要求之後，它會以回應方式傳送 HTTP 訊息。 本節討論可在該回應中找到的參數和標頭。

回應參數

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：已連線 | 已中斷連線 | 暫時中斷連線

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>

X-WNS-Status

此標頭描述 WNS 如何處理通知要求。 這可以使用，而不是將響應碼解譯為成功或失敗。

X-WNS-Status：received |dropd |channelthrottled

MS-CV

此標頭提供與主要用於偵錯之要求相關的相互關聯向量。 如果提供 CV 作為要求的一部分，則 WNS 會使用此值，否則 WNS 將產生並回應 CV。 當向 WNS 回報問題時，需要此標頭以及 X-WNS-Debug-Trace 和 X-WNS-Msg-ID 標頭。

MS-CV： <string value>

回應碼

每個 HTTP 訊息都包含其中一個回應碼。 WNS 建議開發人員記錄回應碼以用於偵錯。 當開發人員向 WNS 回報問題時，必須提供回應碼和標頭資訊。

不支援的 HTTP 功能

WNS Web 介面支援 HTTP 1.1，但不支援下列功能：

• Chunking
• 導管處理 （POST 不是等冪）
• 雖然支援，但開發人員應該停用 Expect-100，因為這樣會在傳送通知時造成延遲。