푸시 알림 서비스 요청 및 응답 헤더(Windows 런타임 앱)

이 항목에서는 푸시 알림을 보내는 데 필요한 서비스 간 웹 API 및 프로토콜에 대해 설명합니다.

푸시 알림 및 WNS 개념, 요구 사항 및 작업에 대한 개념적 논의는 WNS(Windows Push Notification Services) 개요 참조하세요.

액세스 토큰 요청 및 받기

이 섹션에서는 WNS를 사용하여 인증할 때 관련된 요청 및 응답 매개 변수에 대해 설명합니다.

액세스 토큰 요청

HTTP 요청은 클라우드 서비스를 인증하고 그 대가로 액세스 토큰을 검색하기 위해 WNS로 전송됩니다. SSL(보안 소켓 계층)를 사용하여 요청이 https://login.live.com/accesstoken.srf으로 발송됩니다.

액세스 토큰 요청 매개 변수

클라우드 서비스는 "application/x-www-form-urlencoded" 형식을 사용하여 HTTP 요청 본문에 이러한 필수 매개 변수를 제출합니다. 모든 매개 변수가 URL로 인코딩되었는지 확인해야 합니다.

액세스 토큰 응답

WNS는 클라우드 서비스를 인증하고, 성공하면 액세스 토큰을 포함하여 "200 OK"로 응답합니다. 그렇지 않으면 WNS는 OAuth 2.0 프로토콜 초안설명된 대로 적절한 HTTP 오류 코드로 응답합니다.

액세스 토큰 응답 매개 변수

클라우드 서비스가 성공적으로 인증되면 액세스 토큰이 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 기능

알림 요청 보내기

알림 요청을 보낼 때 호출 앱은 채널 URI(Uniform Resource Identifier)에 주소가 지정된 SSL을 통해 HTTP 요청을 수행합니다. "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에 대해 배지 1개, 타일 1개, 알림 메시지 1개를 캐시합니다. 기본적으로 원시 알림은 캐시되지 않지만 원시 알림 캐싱을 사용하도록 설정하면 하나의 원시 알림이 캐시됩니다. 항목은 캐시에 무기한 보관되지 않으며 적절한 기간 후에 삭제됩니다. 그렇지 않으면 다음 디바이스가 온라인 상태가 되면 캐시된 콘텐츠가 배달됩니다.

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: 참 | 거짓

X-WNS-Group

X-WNS-그룹: <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; 모두

알림 응답 보내기

WNS는 알림 요청을 처리한 후 응답으로 HTTP 메시지를 보냅니다. 이 섹션에서는 해당 응답에서 찾을 수 있는 매개 변수 및 헤더에 대해 설명합니다.

응답 매개 변수

X-WNS-Debug-Trace

이 헤더는 유용한 디버깅 정보를 문자열로 반환합니다. 개발자가 문제를 디버그하는 데 도움이 되도록 이 헤더를 기록하는 것이 좋습니다. 이 헤더는 X-WNS-Msg-ID 헤더 및 MS-CV와 함께 WNS에 문제를 보고할 때 필요합니다.

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

X-WNS-DeviceConnectionStatus

이 헤더는 알림 요청의 XWNS-RequestForStatus 헤더에서 요청된 경우 호출 애플리케이션에 디바이스 상태를 반환합니다.

X-WNS-DeviceConnectionStatus: 연결됨 | 연결 끊김 | tempdisconnected

X-WNS-Error-Description

이 헤더는 디버깅에 도움이 되도록 기록해야 하는 사람이 읽을 수 있는 오류 문자열을 제공합니다.

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

X-WNS-Msg-ID

이 헤더는 호출자에게 알림에 대한 식별자를 제공하는 데 사용됩니다. 문제를 디버그하는 데 도움이 되도록 이 헤더를 기록하는 것이 좋습니다. 이 헤더는 X-WNS-Debug-Trace 및 MS-CV와 함께 WNS에 문제를 보고할 때 필요합니다.

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

X-WNS-Status

이 헤더는 WNS가 알림 요청을 처리하는 방법을 설명합니다. 응답 코드를 성공 또는 실패로 해석하는 대신 사용할 수 있습니다.

X-WNS-Status: 수신됨 | 드롭됨 | 채널제한됨

MS-CV

이 헤더는 주로 디버깅에 사용되는 요청과 관련된 상관 관계 벡터를 제공합니다. CV가 요청의 일부로 제공되면 WNS는 이 값을 사용하며, 그렇지 않으면 WNS는 CV를 생성하고 다시 응답합니다. 이 헤더는 X-WNS-Debug-Trace 및 X-WNS-Msg-ID 헤더와 함께 WNS에 문제를 보고할 때 필요합니다.

MS-CV: <string value>

응답 코드

각 HTTP 메시지에는 이러한 응답 코드 중 하나가 포함됩니다. WNS는 개발자가 디버깅에 사용할 응답 코드를 기록하는 것이 좋습니다. 개발자는 WNS에 문제를 보고할 때 응답 코드 및 헤더 정보를 제공해야 합니다.

지원되지 않는 HTTP 기능

WNS 웹 인터페이스는 HTTP 1.1을 지원하지만 다음 기능은 지원하지 않습니다.

• Chunking
• 파이프라이닝(POST는 멱등성이 아님)
• 지원되지만 개발자는 알림을 보낼 때 대기 시간이 발생하므로 Expect-100을 사용하지 않도록 설정해야 합니다.