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

  • 아티클

[ 이 문서는 Windows 런타임 앱을 작성하는 Windows에서 8.x 및 Windows Phone 8.x 개발자를 대상으로 합니다. Windows 10용으로 개발하는 경우에는 최신 설명서를 참조하세요.]

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

푸시 알림, WNS 개념, 요구 사항 및 작업의 개념적 설명은 WNS(Windows 푸시 알림 서비스) 개요를 참조하세요.

액세스 토큰 요청 및 받기

이 섹션에서는 WNS를 사용한 인증 시의 요청 및 응답 매개 변수에 대해 설명합니다.

액세스 토큰 요청

클라우드 서비스를 인증하고 액세스 토큰을 검색하기 위해 HTTP 요청이 WNS로 전송됩니다. 이 요청은 SSL(Secure Sockets Layer)을 사용하여 다음 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 필수 다음과 같이 설정되어야 합니다.
  • Windows: "notify.windows.com"
  • Windows Phone: "notify.windows.com" 또는 "s.notify.live.net"

 

액세스 토큰 응답

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

액세스 토큰 응답 매개 변수

클라우드 서비스가 인증되면 액세스 토큰이 HTTP 응답에 반환됩니다. 만료 시까지 이 액세스 토큰을 알림 요청에 사용할 수 있습니다. HTTP 응답은 "application/json" 미디어 유형을 사용합니다.

매개 변수 필수/옵션 설명
access_token 필수 클라우드 서비스가 알림을 보낼 때 사용하는 액세스 토큰입니다.
token_type 옵션 항상 "bearer"로 반환됩니다.

 

응답 코드

HTTP 응답 코드 설명
200 성공 요청에 성공했습니다.
400 잘못된 요청 인증에 실패했습니다. 응답 매개 변수는 OAuth 초안 RFC(Request for Comments)를 참조하세요.

 

예

성공한 인증 응답의 예는 다음과 같습니다.

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

알림 요청 보내기 및 응답 받기

이 섹션에서는 알림을 전달할 WNS에 대한 HTTP 요청에 관련된 헤더와 응답에 관련된 헤더에 대해 설명합니다.

  • 알림 요청 보내기
  • 알림 응답 보내기
  • 지원되지 않는 HTTP 기능

알림 요청 보내기

알림 요청을 보내는 경우 호출 앱이 SSL을 통해 채널 URI(Uniform Resource Identifier)로 주소가 지정된 HTTP 요청을 수행합니다. "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(Time to Live)을 지정하고 초 단위로 표시되는 정수 값입니다.
X-WNS-SuppressPopup 옵션 Windows Phone만 해당: 알림 자체를 표시하지 않고 관리 센터에 바로 알림 메시지를 전달합니다.
X-WNS-Group 옵션 Windows Phone만 해당: X-WNS-Tag 헤더와 함께 관리 센터에서 알림을 그룹화하는 데 사용됩니다.
X-WNS-Match 경우에 따라 필요합니다. Windows Phone만 해당: HTTP DELETE 메서드를 통해 관리 센터에서 알림 메시지를 제거할 경우 대상을 식별하기 위해 필요합니다.

 

중요 정보

  • 요청에 다른 표준 헤더가 포함되어 있는지 여부에 관계없이 클라이언트에 전달되는 알림에 포함되는 표준 HTTP 헤더는 Content-Length 및 Content-Type뿐입니다.
  • 다른 모든 표준 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
값 설명
캐시 기본값. 사용자가 오프라인 상태이면 알림이 캐시됩니다. 타일 및 배지 알림의 기본 설정입니다.
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=<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 옵션 문제 보고 시 문제 해결에 도움이 되도록 기록해야 하는 디버깅 정보입니다.
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에 문제를 보고할 때 응답 코드와 헤더 정보를 제공해야 합니다.

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 웹 인터페이스는 HTTP 1.1을 지원하지만 다음 기능은 지원하지 않습니다.

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

관련 항목

빠른 시작: 푸시 알림 보내기

푸시 알림에 대한 지침 및 검사 목록

WNS(Windows 푸시 알림 서비스)를 사용하여 인증하는 방법

알림 채널을 요청, 생성 및 저장하는 방법

푸시 알림 및 정기 알림 샘플

WNS 개요