collections.mp.microsoft.com/v8.0/collections/consume

Consume API를 사용하여 다음 Microsoft Store 소모품 유형을 관리할 수 있습니다.

스토어 관리 소모품: 소비된 수량을 보고하고 지정된 사용자의 현재 수량 잔액에서 제거합니다. 사용자는 서비스에서 소비되거나 이행된 것으로 보고할 필요 없이 스토어 관리 소모품을 반복적으로 재구매할 수 있습니다. 자세한 내용은 스토어 관리 소비 요청을 참조하세요.
개발자 관리 소모품: 지정된 사용자에 대해 소모품 제품을 이행된 것으로 보고합니다. 사용자가 개발자 관리 소모품 제품을 재구매하기 전에 앱 또는 서비스는 해당 사용자에 대해 소모품 제품을 이행된 것으로 보고해야 합니다. 자세한 내용은 개발자 관리 소비 요청을 참조하세요.

`trackingId`를 사용하여 이행 완료 유효성 검사

trackingId는 재시도에 안전한 이행 유효성 검사를 제공합니다. 서비스가 확인 응답을 받지 못하면 동일한 요청 본문을 다시 보냅니다. 서비스는 이전 요청을 인식하고 재시도를 확인 검사로 처리합니다. API에 대한 각 요청에는 고유한 trackingId가 있어야 합니다. 원래 요청이 성공하지 못했거나 응답을 받지 못한 경우, 요청을 재시도하면 서비스가 요청된 트랜잭션을 완료합니다. 이전 요청에서 이행이 완료된 경우, API는 요청을 인식하고 확인 응답을 보냅니다. 이 경우 API는 사용자의 잔액에서 두 번째로 이행하거나 차감하지 않습니다. 대신 API는 항목이 사용자의 남은 잔액과 함께 소비된 것처럼 성공으로 응답합니다. 따라서 요청이 이행되었다는 확인 응답을 받을 때까지 각 요청의 값과 trackingId를 서버 또는 로그에 캐시하세요. 예제는 Game Service 샘플을 참조하세요. 요청에 includeOrderIds 매개 변수가 있는 경우, 소모품의 제품 유형에 따라 다음 동작이 예상됩니다.

소모품 유형	첫 번째 소비 요청 동작	재시도 소비 요청 동작
스토어 관리	요청을 이행하는 데 사용된 OrderIds가 반환됩니다	요청을 이행하는 데 사용된 동일한 OrderIds가 반환됩니다
개발자 관리	요청을 이행하는 데 사용된 OrderIds가 반환됩니다	이 제품 유형에는 이 데이터가 추적되지 않으므로 OrderID가 반환되지 않습니다

개발자 관리 소모품을 사용하는 경우 재시도 요청에서 주문 ID를 가져올 수 없습니다.

필수 구성 요소

서비스 간 API의 필수 구성 요소를 검토하세요. 이 API는 Microsoft Entra ID 및 위임된 인증 X-token 인증 유형을 모두 지원합니다.

개발자 관리 소모품에 대한 샌드박스 제한: 개발 샌드박스(RETAIL이 아닌)에서 개발자 관리 소모품 제품을 소비할 때 사용자 저장소 ID 또는 Microsoft Entra ID를 사용한 인증은 지원되지 않습니다. 샌드박스 환경에서는 개발자 관리 소모품 제품을 성공적으로 소비하려면 위임된 권한 부여 XSTS 토큰을 사용해야 합니다. 이 제한은 스토어 관리 소모품이나 RETAIL 샌드박스에는 적용되지 않습니다.

파트너 센터에서 제품 구성을 게시하지 않으면 호출이 성공하지만 결과가 반환되지 않을 수 있습니다.

사용자 저장소 ID 인증 오류 코드

Code	Error	Inner error code	Description
401	Unauthorized	AuthenticationTokenInvalid	Microsoft Entra ID 액세스 토큰이 잘못되었습니다. 어떤 경우에는 `ServiceError`의 세부 정보에 토큰이 만료되었거나 `appid` 클레임이 누락된 경우와 같은 자세한 정보가 포함됩니다.
401	Unauthorized	PartnerAadTicketRequired	Microsoft Entra ID 액세스 토큰이 권한 부여 헤더에서 서비스에 전달되지 않았습니다.
401	Unauthorized	InconsistentClientId	요청 본문의 Microsoft Store ID 키에 있는 `clientId` 클레임과 권한 부여 헤더의 Microsoft Entra ID 액세스 토큰에 있는 `appid` 클레임이 일치하지 않습니다.

X-token 인증 사용 시 오류 코드

Code	Error	Inner error code	Description
401	Unauthorized	Expired Token	X-token이 만료되었으며 호출을 완료하려면 새 토큰이 필요합니다.
403	Unauthorized	Invalid Token	사용된 토큰은 이 엔드포인트에서 인증할 권한이 없습니다. 토큰이 잘못된 샌드박스 또는 신뢰 당사자용일 수 있습니다.
429	Throttled	Too frequent calls	지정된 호출 제한 내에서 사용자에 대해 서비스가 너무 많이 호출되었습니다. 서비스가 이 사용자에 대해 다른 호출을 서비스에 언제 수행할 수 있는지에 대한 정보는 응답을 참조하세요.

요청

요청 구문

Method	Request URI
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/consume`

요청 헤더

Header	Type	Description
`Authorization`	`string`	필수. 사용 중인 인증 유형에 따라 위임된 권한 부여 X-token 또는 Microsoft Entra ID 액세스 토큰 중 하나입니다.
`Signature`	`string`	X-token으로 인증할 때 필수입니다. 사용자 저장소 ID 인증에는 필요하지 않습니다.
`User-Agent`	`string`	선택 사항이지만 권장됩니다. 로깅 및 조사를 위해 서비스를 식별하는 데 도움이 됩니다.
`Host`	`string`	값 `collections.mp.microsoft.com`으로 설정해야 합니다.
`Content-Length`	`number`	요청 본문의 길이입니다.
`Content-Type`	`string`	요청 및 응답 형식을 지정합니다. 현재 지원되는 유일한 값은 `application/json`입니다.

요청 본문

Parameter	Type	Description	Required
`beneficiary`	`UserIdentity`	이 항목이 소비되는 사용자입니다. 자세한 내용은 Microsoft Entra ID 및 사용자 저장소 ID로 인증을 참조하세요. X-token 인증에는 필요하지 않습니다.	사용자 저장소 ID 인증에만 해당
`trackingId`	`guid`	중복 검사를 위해 개발자가 제공한 고유한 `trackingId`입니다. GUID는 각 요청에 대해 고유해야 합니다. 자세한 내용은 trackingId를 사용하여 이행 완료 유효성 검사를 참조하세요.	예
`productId`	`string`	요청에 대한 소모품의 `productId`입니다. 파트너 센터 또는 서비스에서 사용자의 제품 및 자격 쿼리를 통해 얻을 수 있습니다.	예
`removeQuantity`	`int`	사용자의 현재 잔액에서 소비할 수량입니다.	스토어 관리 소모품에만 적용됩니다.
`includeOrderIds`	`bool`	소비 요청을 이행하는 데 사용된 주문의 OrderIds 및 LineItemIds를 포함합니다. 이 값은 Clawback 이벤트 서비스 결과와 함께 사용하여 게임 서비스에서 환불된 소비 트랜잭션을 식별할 수 있습니다.	아니요
`sbx`	`string`	UserStoreIds로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다. 참고: 개발자 관리 소모품의 경우, 개발 샌드박스를 대상으로 하는 `sbx` 매개 변수를 사용한 사용자 저장소 ID 인증은 지원되지 않습니다. 개발자 관리 소모품의 샌드박스 테스트에는 XSTS 토큰 인증을 사용하세요.	아니요

소비 요청 예제

다음 예제에서는 인증에 사용자 저장소 ID를 사용하며 요청 JSON 본문에 beneficiary 개체가 필요합니다.

스토어 관리 소비 요청

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}

개발자 관리 소비 요청

다음 예제에서는 사용자 저장소 ID 인증을 사용합니다. 그러나 이 인증 방법은 개발 샌드박스의 개발자 관리 소모품에는 작동하지 않습니다. 샌드박스 환경에서 테스트하는 경우 XSTS 토큰 인증을 대신 사용하세요. 자세한 내용은 위임된 인증 XSTS 토큰을 통한 인증을 참조하세요.

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}

응답

응답 본문

Parameter	Type	Description	Required
`itemId`	string	사용자가 소유한 다른 항목과 컬렉션 항목을 구별하는 ID입니다. 이 ID는 제품별로 고유합니다.	예
`productId`	`string`	Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.	예
`trackingId`	`GUID`	소비 요청을 위해 호출자가 제공한 고유한 `trackingId`입니다.	예
`newQuantity`	`int`	이 소모품 제품에 대한 사용자 잔액의 남은 수량입니다. 개발자 관리 소모품의 경우 값은 0입니다.	예
`orderTransactions`	`List<ConsumeOrderTransaction>`	요청을 이행하는 데 사용된 주문을 나타내는 ConsumeOrderTransaction 개체의 배열입니다. 요청에서 `includeOrderIds` 매개 변수가 true로 설정된 경우에만 반환됩니다. 자세한 내용은 다음 표를 참조하세요.	아니요

ConsumeOrderTransaction 개체에는 다음 매개 변수가 포함됩니다.

Parameter	Type	Description	Required
`orderId`	`GUID`	소비 요청의 전체 또는 일부를 이행하는 데 사용된 사용자의 구매 주문 ID입니다.	예
`orderLineItemId`	`GUID`	사용자가 수행한 구매 주문 내 소모품이 있었던 라인 항목의 ID입니다. OrderID당 여러 LineItemId가 있을 수 있기 때문에 이 ID는 OrderId보다 소모품 구매에 대해 더 고유합니다.	예
`quantityConsumed`	`int`	이 특정 OrderId / LineItemId로 이행된 요청의 수량입니다.	예

소비 응답 예제

HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}

Microsoft Store APIs

`trackingId`를 사용하여 이행 완료 유효성 검사

필수 구성 요소

사용자 저장소 ID 인증 오류 코드

X-token 인증 사용 시 오류 코드

요청

요청 구문

요청 헤더

요청 본문

소비 요청 예제

스토어 관리 소비 요청

개발자 관리 소비 요청

응답

응답 본문

소비 응답 예제

관련 문서

​trackingId를 사용하여 이행 완료 유효성 검사

​필수 구성 요소

​사용자 저장소 ID 인증 오류 코드

​X-token 인증 사용 시 오류 코드

​요청

​요청 구문

​요청 헤더

​요청 본문

​소비 요청 예제

​스토어 관리 소비 요청

​개발자 관리 소비 요청

​응답

​응답 본문

​소비 응답 예제

​관련 문서

`trackingId`를 사용하여 이행 완료 유효성 검사

필수 구성 요소

사용자 저장소 ID 인증 오류 코드

X-token 인증 사용 시 오류 코드

요청

요청 구문

요청 헤더

요청 본문

소비 요청 예제

스토어 관리 소비 요청

개발자 관리 소비 요청

응답

응답 본문

소비 응답 예제

관련 문서