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

아티클
06/20/2024

사용 API를 통해 Microsoft Store 내에서 다음과 같은 유형의 소모성 제품을 관리할 수 있습니다.

Store 관리형 소모성 제품: 사용된 수량을 보고하고 지정한 사용자의 현재 남은 수량에서 제거합니다. 사용자는 서비스에서 이를 사용됨 또는 처리됨으로 보고할 필요 없이 Microsoft Store 관리 소모성 제품을 반복해서 재구매할 수 있습니다. 자세한 내용은 스토어 관리 소비 요청을 참조하세요.
개발자 관리 소모성 제품 - 지정된 고객에 대해 소모성 제품을 처리됨으로 보고합니다. 사용자가 개발자 관리 소모성 제품을 다시 구입하려면 앱 또는 서비스에서 해당 사용자에 대해 소모성 제품이 처리됨으로 보고되어야 합니다. 자세한 내용은 개발자 관리 소비 요청을 참조하세요.

trackingId를 사용하여 처리 완료 확인

trackingId이(가) 중복 검사로 사용되어, 서비스가 확인을 받지 못한 경우 처리 요청을 성공한 것으로 확인합니다. 서비스가 확인 응답을 받을 수 없는 상태가 발생한 경우 동일한 요청 본문(추적 ID 포함)으로 요청을 다시 제출하고 처리 성공 확인을 다시 받은 후에 게임 아이템을 소모성 제품으로 허용할 수 있습니다.

각 사용 요청에는 고유한 추적 ID가 있어야 합니다. 이는 항상 사용 요청과 연결되며 유효성 검사에 대해 무제한으로 다시 제출할 수 있습니다. 사용 시 요청을 받지 못했거나 처리되지 않은 경우 서비스에서 요청된 트랜잭션을 정상적으로 완료합니다. 이전 요청에서 처리가 완료된 경우 값과 trackingId이(가) 동일하므로 사용에서 이를 확인 요청으로 인식합니다. 이 경우 사용 시 사용자의 남은 시간에서 시간을 처리하거나 차감하지 않습니다. 이를 대신하여, 사용 서비스에서 사용이 발생한 것과 같이 동일한 형식으로 성공 응답을 보내고 남은 시간을 다시 전달합니다.

따라서 요청이 처리되었다는 확인 응답을 수신하기 전까지 서버 또는 로그에 캐시된 각 요청의 값과 trackingId을(를) 유지하는 것이 좋습니다. 예시는 게임 서비스 샘플을 참조하세요.

재시도 요청에서 includeOrderIds 매개 변수를 사용하면 제품의 소모성 제품 유형에 따라 다음이 발생합니다.

소모성 제품 유형	첫 번째 사용 요청 동작	사용 요청 동작 재시도
Microsoft Store 관리	반환된 사용 요청을 수행하는 데 사용된 주문 ID	사용 요청을 수행하는 데 사용된 동일한 주문 ID가 반환됨
개발자 관리형	반환된 사용 요청을 수행하는 데 사용된 주문 ID	이 제품 유형에 대한 사용 후 이 데이터가 추적되지 않으므로 ID가 반환되지 않습니다.

따라서 개발자 관리 소모성 제품을 사용하는 경우 통화가 사용되었는지 확인하기 위한 재시도 확인인 경우 이행의 주문 ID 정보를 얻을 수 없다는 점을 알아두세요.

필수 조건

이 API를 사용하려면 다음 인증 유형 중 하나를 사용해야 합니다.

신뢰 당사자 http://licensing.xboxlive.com의 위임 인증 XSTS 토큰
대상 그룹 URI 값이 있는 Microsoft Entra ID 액세스 토큰이 있는 Microsoft Store ID 키 https://onestore.microsoft.com

보다 상세한 안내는 Microsoft Store API를 사용한 서비스 인증을 참조합니다.

또한 서비스에 표시하려는 제품은 서비스에서 컬렉션 서비스를 호출하는 데 사용하는 인증 유형에 따라 파트너 센터에서 추가 구성이 필요합니다. 파트너 센터에서 제품을 올바르게 구성하는 방법은 다음을 참조하세요.

사용자 Store ID / Microsoft Entra ID 인증이 있는 제품을 보고 관리하려면 추가 구성이 필요합니다.
위임 인증 XSTS 토큰을 사용하여 제품을 확인하고 관리하는 데 필요한 추가 구성

참고 항목

제품 구성이 완료되어 파트너 센터를 통해 게시되지 않은 경우 Collections에 대한 호출은 성공하지만 응답에 결과가 없습니다.

사용자 Microsoft Store ID 인증 오류 코드

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

XSTS 토큰 인증을 사용하는 오류 코드

코드	오류	내부 오류 코드	설명
401	Unauthorized	Expired Token	XSTS 토큰이 만료되었으므로 호출을 완료하려면 새로운 토큰이 필요합니다.
403	Unauthorized	Invalid Token	사용된 토큰이 이 끝점에서 인증할 권한이 없습니다. 잘못된 샌드박스 또는 신뢰 당사자의 토큰일 수 있습니다.
429	Throttled	Too frequent calls	지정된 호출 한도 내에서 사용자에 대해 너무 많은 호출이 이루어졌습니다. 서비스에서 이 사용자에 대한 다른 호출을 할 수 있는 시기에 대한 상세한 정보는 응답을 참조합니다.

요청

요청 구문

메서드	요청 URI
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/consume`

요청 헤더

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

요청 본문

매개 변수	형식	설명	필수
`beneficiary`	`UserIdentity`	이 항목을 사용 중인 사용자입니다. 보다 상세한 안내는 사용자 Store ID를 통한 PC 타이틀 인증을 참조합니다. XSTS 토큰 인증에는 필요하지 않습니다.	사용자 Microsoft Store ID 인증에만 필요합니다.
`trackingId`	`guid`	중복 확인을 위해 개발자가 제공하는 고유한 추적 ID입니다. GUID는 각 요청에 대해 고유해야 합니다. 자세한 내용은 trackingId를 사용하여 처리 완료 유효성 검사를 참조합니다.	예
`productId`	`string`	요청 대상인 소모성 제품의 `productId`입니다. 파트너 센터에서 또는 서비스에서 사용자의 제품 및 권한 쿼리를 통해 획득할 수 있습니다.	예
`removeQuantity`	`int`	사용자의 수량에서 사용할 수량입니다.	Microsoft Store 관리 소모성 제품에 대해서만 필요합니다.
`includeOrderIds`	`bool`	이 사용 요청을 수행하는 데 사용되는 주문의 OrderIds 및 LineItemIds를 포함합니다. 그런 다음 이러한 값을 Clawback 이벤트 서비스 결과와 함께 사용하여 게임 서비스에서 환불된 사용 트랜잭션을 식별할 수 있습니다.	아니요
`sbx`	`string`	결과의 범위를 지정해야 하는 샌드박스를 지정하는 UserStoreIds로 인증하기 위한 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증에는 X-Token 내에 Sandbox가 지정되어 있으므로 이 값이 필요하지 않습니다.	아니요

사용 요청 예시

다음 예에서는 인증을 위해 사용자 저장소 ID를 사용하고 요청 JSON 본문에 수혜자 개체가 필요합니다.

매장 관리 사용 요청

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
}

개발자 관리 사용 요청

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
}

응답

응답 본문

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

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

매개 변수	형식	설명	필수
`orderId`	`GUID`	이 사용 요청의 전체 또는 일부를 수행하는 데 사용되는 사용자의 구매 주문 ID입니다.	예
`orderLineItemId`	`GUID`	소모성 제품 항목의 ID가 사용자가 만든 구매 주문서 내에 있었습니다. 이 ID는 주문 ID당 여러 개의 품목 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 API를 사용하여 서비스 인증

PublisherQuery(Collections v9)를 사용하여 사용자 제품 및 자격 쿼리

서비스의 소모성 제품 관리

서비스에서 환불 및 지불 거절 관리

다음을 통해 공유

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

trackingId를 사용하여 처리 완료 확인

필수 조건

사용자 Microsoft Store ID 인증 오류 코드

XSTS 토큰 인증을 사용하는 오류 코드

요청

요청 구문

요청 헤더

요청 본문

사용 요청 예시

매장 관리 사용 요청

개발자 관리 사용 요청

응답

응답 본문

응답 사용 예제

추가 리소스

다음을 통해 공유

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

trackingId를 사용하여 처리 완료 확인

필수 조건

사용자 Microsoft Store ID 인증 오류 코드

XSTS 토큰 인증을 사용하는 오류 코드

요청

요청 구문

요청 헤더

요청 본문

사용 요청 예시

매장 관리 사용 요청

개발자 관리 사용 요청

응답

응답 본문

응답 사용 예제

관련 항목

추가 리소스