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

  • 아티클

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

푸시 알림 및 WNS 개념, 요구 사항 및 운영에 대한 개념적 설명은 WNS(Windows 푸시 알림 서비스) 개요를 참조하세요.

액세스 토큰 요청 및 받기

이 섹션에서는 WNS로 인증할 때 개입되는 요청 및 응답 매개 변수에 대해 설명합니다.

액세스 토큰 요청

HTTP 요청은 클라우드 서비스를 인증하고 반환되는 액세스 토큰을 검색하기 위해 WNS로 전송됩니다. SSL(Secure Sockets Layer)을 사용하여 요청이 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는 OAuth 2.0 프로토콜 초안에 설명된 대로 적절한 HTTP 오류 코드로 응답합니다.

액세스 토큰 응답 매개 변수

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

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

응답 코드

HTTP 응답 코드 설명
200 OK 요청에 성공했습니다.
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",
     "expires_in": 86400
 }

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

이 섹션에서는 알림을 전달하기 위해 WNS에 대한 HTTP 요청에 사용되는 헤더와 회신에 사용되는 헤더에 대해 설명합니다.

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

알림 요청 보내기

알림 요청을 보낼 때 호출 앱은 채널 URI(Uniform Resource Identifier)로 주소가 지정되는 SSL을 통해 HTTP 요청을 만듭니다. "Content-Length"는 요청에 지정해야 하는 표준 HTTP 헤더입니다. 그 외의 모든 표준 헤더는 선택 사항이거나 지원되지 않습니다.

또한 여기에 나열된 사용자 지정 요청 헤더를 알림 요청에 사용할 수 있습니다. 필수인 헤더도 있고 선택 사항인 헤더도 있습니다.

요청 매개 변수

헤더 이름 Required 설명
Authorization 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(Time to Live)을 지정하는 정수 값(초)입니다.
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
값 설명
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에 대해 배지 1개, 타일 1개 및 알림 메시지 1개를 캐시합니다. 기본적으로 원시 알림은 캐시되지 않지만, 원시 알림 캐싱이 사용되면 하나의 원시 알림이 캐시됩니다. 항목은 캐시에 무기한으로 보관되는 것이 아니라 적절한 시간이 경과한 후 삭제됩니다. 삭제되지 않은 경우 디바이스가 다음에 온라인 상태가 될 때 캐시된 콘텐츠가 전송됩니다.

X-WNS-Cache-Policy: cache | no-cache
값 설명
캐시 기본값. 사용자가 오프라인이면 알림이 캐시됩니다. 타일 및 배지 알림의 기본 설정입니다.
no-cache 사용자가 오프라인이면 알림이 캐시되지 않습니다. 원시 알림의 기본 설정입니다.

X-WNS-RequestForStatus

응답에 디바이스 상태 및 WNS 연결 상태를 포함할지 여부를 지정합니다. 선택 사항입니다.

    X-WNS-RequestForStatus: true | false
값 설명
true 응답에 디바이스 상태 및 알림 상태를 반환합니다.
false 기본값. 디바이스 상태 및 알림 상태를 반환하지 않습니다.

X-WNS-Tag

알림에 태그 레이블을 할당합니다. 이 태그는 앱이 알림 순환을 옵트인할 때 알림 큐의 타일 대체 정책에 사용됩니다. 이 태그가 지정된 알림이 큐에 이미 있으면 동일한 태그가 지정된 새 알림이 기존 태그를 대체합니다.

참고 항목

이 헤더는 선택 사항이며 타일 알림을 보낼 때만 사용됩니다.

    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 메시지를 보냅니다. 이 섹션에서는 해당 응답에서 찾을 수 있는 매개 변수 및 헤더에 대해 설명합니다.

응답 매개 변수

헤더 이름 Required 설명
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>

값 설명
문자열 값 영숫자 문자열입니다.

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

값 설명
연결됨 디바이스가 온라인 상태이고 WNS에 연결되었습니다.
연결 끊김 디바이스가 오프라인 상태이며 WNS에 연결되지 않았습니다.
tempconnected 3G 연결이 끊어지거나 랩톱의 무선 스위치를 누른 경우처럼 디바이스와 WNS의 연결이 일시적으로 끊어졌습니다. 알림 클라이언트 플랫폼에는 의도적인 연결 해제가 아닌 일시적인 중단으로 표시됩니다.

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>

값 설명
문자열 값 16자 이하의 영숫자 문자열입니다.

X-WNS-Status

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

X-WNS-Status: received | dropped | channelthrottled

값 설명
received WNS에서 알림을 받아 처리했습니다. 참고:�장치가 알림을 수신했다는 것을 보장하지는 않습니다.
dropped 오류 때문에 또는 클라이언트가 알림을 명시적으로 거부하여 알림이 명시적으로 삭제되었습니다. 디바이스가 오프라인인 경우에도 알림이 삭제됩니다.
channelthrottled 앱 서버가 이 특정 채널의 속도 제한을 초과하여 알림이 삭제되었습니다.

MS-CV

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

Important

사용자 고유의 CV를 제공하는 경우 푸시 알림 요청마다 새 CV를 생성해야 합니다.

MS-CV: <string value>

값 설명
문자열 값 상관 관계 벡터 표준을 따릅니다.

응답 코드

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

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