推播通知服務要求和回應標頭 (Windows 執行階段應用程式)
[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱 最新文件 ]
這個主題說明傳送推播通知所需的服務對服務 Web API 與通訊協定。
如需推播通知、WNS 概念、需求和操作的概念討論，請參閱 Windows 推播通知服務 (WNS) 概觀。
要求和接收存取權杖
本節說明以 WNS 進行驗證時牽涉到的要求與回應參數。
存取權杖要求
將 HTTP 要求傳送至 WNS，以驗證雲端服務，然後擷取存取權杖。使用安全通訊端層 (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 | 必要 | 必須設為：
|
存取權杖回應
WNS 會驗證雲端服務，並在成功後，以 "200 OK" 回應，其中包括存取權杖。否則，WNS 會以適當的 HTTP 錯誤碼回應，如 OAuth 2.0 通訊協定草稿中所述。
存取權杖回應參數
如果成功驗證雲端服務，就會在 HTTP 回應中傳回存取權杖。在此存取權杖到期之前，都可用於通知要求。HTTP 回應使用 "application/json" 媒體類型。
| 參數 | 必要/選用 | 說明 |
|---|---|---|
| access_token | 必要 | 雲端服務在傳送通知時使用的存取權杖。 |
| token_type | 選用 | 永遠傳回 "bearer"。 |
回應碼
| HTTP 回應碼 | 說明 |
|---|---|
| 200 確定 | 要求成功。 |
| 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"
}
傳送通知要求和接收回應
本節說明 HTTP 要求中所含可送至 WNS 來傳遞通知的標頭，以及與回覆有關的那些標頭。
- 傳送通知要求
- 傳送通知回應
- 不支援的 HTTP 功能
傳送通知要求
傳送通知要求時，呼叫應用程式可透過 SSL 發出 HTTP 要求，送到通道統一資源識別元 (URI)。"Content-Length" 是要求中必須指定的標準 HTTP 標頭。所有其他標準標頭皆為選擇性或不受支援。
此外，這裡列出的自訂要求標頭皆可用於通知要求。有些是必要標頭，有些則是選擇性的。
要求參數
| 標頭名稱 | 必要/選用 | 說明 |
|---|---|---|
| 授權 | 必要 | 用以驗證通知要求的標準 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 | 選用 | 指定存留時間 (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 標頭會被忽略，或在不支援該功能時傳回錯誤。
授權
授權標頭是用來指定呼叫者的認證 (遵循 bearer 權杖的 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 會為每個應用程式快取一個徽章與一個磚通知。如果啟用應用程式的通知循環功能，WNS 最多將可快取 5 個磚通知。預設不會快取原始通知，但如果啟用了原始通知快取，便會快取一個原始通知。項目不會永久保留在快取中，會在一段期間後丟棄。或者，在裝置下次連線時，傳遞快取的內容。
此標頭可以忽略，而且應該只在雲端服務想要覆寫預設快取行為時才使用。
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 市集應用程式重要訊息中心的特定快顯通知、一組快顯通知 (依標記或群組分類) 或所有快顯通知移除。此標頭可指定群組、標記或同時指定兩者。此標頭在 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=<字串值> | 移除有指定標記和群組標籤的單一通知。 |
| 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
此標頭會以字串的形式傳回有用的偵錯資訊。建議您記錄此標頭，以協助開發人員偵錯問題。向 WNS 回報問題時，此標頭必須和 X-WNS-Msg-ID 標頭一起使用。
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 連線中斷或是膝上型電腦的無線交換器故障時。「通知用戶端平台」將此視為暫時中斷，而非刻意中斷連線。 |
X-WNS-Error-Description
此標頭提供為了協助偵錯而應記錄的一般人易懂錯誤字串。
X-WNS-Error-Description: <string value>
| 值 | 說明 |
|---|---|
| 字串值 | 英數字串。 |
X-WNS-Msg-ID
此標頭是用來將通知識別碼提供給呼叫者。建議您記錄此標頭以協助偵錯問題。向 WNS 回報問題時，此標頭必須和 X-WNS-Debug-Trace 標頭一起使用。
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 確定 | WNS 已接受該通知。 | 不需採取任何動作。 |
| 400 要求錯誤 | 指定的一或多個標頭不正確或是與另一個標頭發生衝突。 | 記錄要求的詳細資料。檢查要求，然後與本文件進行比對。 |
| 401 未授權 | 雲端服務未提供有效的驗證票證。OAuth 票證可能無效。 | 使用存取權杖要求來驗證雲端服務，以要求有效的存取票證。 |
| 403 禁止 | 未授權雲端服務將通知傳送至這個 URI，即使已經過驗證。 | 要求中提供的存取權杖與要求通道 URI 的應用程式認證不相符。請確定應用程式資訊清單中的套件名稱符合在儀表板中指定給應用程式的雲端服務認證。 |
| 404 找不到 | 通道 URI 無效或是無法由 WNS 辨識。 | 記錄要求的詳細資料。不要再將通知傳送至此通道；送至此位址的通知將會失敗。 |
| 405 方式不允許 | 無效的方法 (GET, CREATE)；只允許 POST (Windows 或 Windows Phone) 或 DELETE (僅適用於 Windows Phone)。 | 記錄要求的詳細資料。切換成使用 HTTP POST。 |
| 406 無法接受 | 雲端服務超過節流限制。 | 記錄要求的詳細資料。降低傳送通知的速率。 |
| 410 不存在 | 通道已過期。 | 記錄要求的詳細資料。不要再將通知傳送至此通道。使應用程式要求新的通道 URI。 |
| 413 要求的實體太大 | 通知承載超過 5000 位元組大小限制。 | 記錄要求的詳細資料。檢查承載以確定其大小未超過限制。 |
| 500 內部伺服器錯誤 | 內部失敗導致通知傳遞失敗。 | 記錄要求的詳細資料。透過開發人員論壇回報問題。 |
| 503 服務無法使用 | 伺服器目前無法使用。 | 記錄要求的詳細資料。透過開發人員論壇回報問題。 |
如需關於特定回應碼的詳細疑難排解資訊，請參閱磚、快顯通知以及徽章通知的疑難排解。另請參閱 COM Error Codes (WPN, MBN, P2P, Bluetooth)。
不支援的 HTTP 功能
WNS Web 介面支援 HTTP 1.1，但是不支援下列功能：
- 區塊化
- 管線化 (POST 並非等冪)
- 即使會支援，開發人員仍然必須停用 Expect-100，因為在傳送通知時會造成延遲。