Microsoft Store v8 Collections b2bLicensePreview API - XBOX Game Development Documentation

b2bLicensePreview API를 사용하면 사용자의 제품 및 자격을 자체 서비스에서 쿼리할 수 있습니다. 쿼리를 특정 제품, 제품 유형으로 제한하거나 쿼리에 다른 필터를 사용할 수 있습니다. 사용자당 시간 창을 기준으로 하는 호출 속도 제한을 피하기 위해 서비스에서 사용자 구매를 정기적으로 폴링하지 않아야 합니다. 현재 제한은 동일한 사용자에 대해 5분 창 내에 100개의 쿼리 요청입니다. 속도 제한을 트리거하면 다음 요청을 수행할 수 있는 시점에 대한 정보와 함께 429 HTTP 응답이 발생합니다. 결과에는 서비스가 대신 호출하고 있는 사용자 계정이 직접 소유하거나 자격이 있는 제품만 포함됩니다. 클라이언트에 표시될 수 있는 공유 자격은 반환되지 않습니다. 공유 시나리오에 대한 자세한 내용은 게임을 위한 제품 공유 모델을 참조하세요.

응답 시간 초과와 긴 응답 시간을 방지하려면 요청에서 productSkuIds 매개 변수를 사용하여 결과에 원하는 정확한 제품을 항상 지정해야 합니다.

productSkuIds 목록 없이 호출하면 사용자가 XBOX 및 Microsoft Store 앱에서 수행한 총 자격 및 구매 수에 따라 응답 시간이 길어집니다.

b2bLicensePreview는 파트너 서비스에서의 호출용입니다.

클라이언트 앱 또는 게임은 이 서비스를 직접 호출해서는 안 됩니다.

제품을 쿼리하는 데 b2bLicensePreview(Collections v8)와 publisherQuery(Collections v9) 비교

b2bLicensePreview(Collections v8)는 사용자 자격을 쿼리하는 이전 Collections 서비스이지만 파트너 사용을 위해 여전히 사용할 수 있습니다. publisherQuery(Collections v9)는 최신 버전이며 XBOX Game Pass 구독 상태 노출과 같은 확장된 기능을 제공합니다. XBOX Inventory 서비스에서 사용하는 LegacyProductIds에 대한 지원과 같이 파트너가 b2bLicensePreview를 사용하려는 시나리오도 여전히 있습니다. 자세한 내용은 관련 문서 필요에 맞는 올바른 Collections 쿼리 API 선택을 참조하세요.

요청

필수 구성 요소

서비스 간 API의 필수 구성 요소를 검토하세요. 이 API는 Microsoft Entra ID 및 위임된 인증 X-token 인증 유형을 모두 지원합니다. 파트너 센터에서 제품 구성이 게시되지 않으면 호출은 성공하지만 결과가 반환되지 않을 수 있습니다.

요청 구문

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

요청 헤더

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
`beneficiaries`	`UserIdentity`	이 항목이 소비되는 사용자입니다. 자세한 내용은 Microsoft Entra ID 및 사용자 저장소 ID로 인증을 참조하세요. X-token 인증에는 필요하지 않습니다.	사용자 저장소 ID 인증에만 해당
`productSkuIds`	`list<ProductSkuId>`	지정된 경우 서비스는 제공된 제품/SKU 쌍에 적용되는 제품만 반환합니다. 더 빠르고 안정적인 결과를 위해 모든 서비스 간 쿼리에 권장됩니다. 자세한 내용은 다음 표를 참조하세요.	아니요
`continuationToken`	`string`	`maxPageSize` 내에 맞지 않는 여러 제품 세트가 있는 경우, 페이지 제한에 도달하면 응답 본문에 연속 토큰이 반환됩니다. 쿼리의 나머지 결과를 검색하려면 후속 호출에서 `continuationToken`을 제공하세요.	아니요
`maxPageSize`	`number`	한 응답에서 반환할 최대 제품 수입니다. 기본값 및 최대값은 100입니다.	아니요
`entitlementFilters`	`list<string>`	쿼리 결과에서 반환할 제품 유형을 지정합니다. 유효한 값 목록은 제품 유형 값 및 의미를 참조하세요.	아니요
`market`	`string`	자격을 확인할 국가/지역/시장입니다. “neutral”을 사용하면(권장) 모든 시장을 검색합니다. 그렇지 않으면 두 문자 ISO 3166 국가/지역 코드(예: US)를 사용합니다.	예
`expandSatisfyingItems`	`bool`	결과에서 번들 또는 구독을 통해 자격이 있는 항목을 포함합니다. `false`로 설정된 경우, 결과에는 상위 번들의 제품 정보와 같이 사용자가 구매한 항목만 포함됩니다. 이 매개 변수를 사용하는 경우 길거나 시간이 초과된 요청을 방지하기 위해 결과를 원하는 제품을 항상 지정하세요.	아니요
`excludeDuplicates`	`bool`	사용자가 여러 소스에서 단일 제품에 대한 자격이 있을 수 있는 중복 자격을 제거합니다.	아니요
`validityType`	`string`	All로 설정하면 만료된 항목을 포함하여 사용자의 모든 제품이 반환됩니다. Valid는 활성 상태이고 시작 날짜 < 현재이며 종료 날짜 > 현재인 제품을 반환합니다. Invalid는 Valid 옵션의 요구 사항을 충족하지 않는 제품을 반환합니다.	아니요
`sbx`	`string`	UserStoreIds로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다.	아니요
`filterSatisfiedByProductIds`	`bool`	제공되지 않은 경우 기본값은 False입니다. False인 경우(권장 값) satisfiedByProductIds 필드의 부여 번들 또는 제품에서 만족되는 자격의 완전한 보기를 제공합니다. True인 경우 satisfiedByProductIds 필드에서 대부분의 만족시키는 ProductID를 필터링하며, 필요에 따라 서비스에서 호환성을 위한 옵션으로 제공됩니다.	아니요

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

Parameter	Type	Description	Required
`productId`	`string`	Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.	예
`skuId`	`string`	Microsoft Store 카탈로그에 제품의 여러 제공 항목이 있는 경우의 특정 SKU 식별자입니다. SKU에 대한 스토어 ID의 예는 0010입니다.	아니요

요청 예제

기본 maxPageSize는 100이지만, 예제에서는 나머지 항목을 요청하는 것을 보여주기 위해 더 낮게 설정되어 있습니다.

POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

응답

응답 본문

Parameter	Type	Description	Required
`continuationToken`	`string`	여러 제품 세트가 있는 경우, 페이지 제한에 도달하면 이 토큰이 반환됩니다. 후속 호출에서 이 연속 토큰을 지정하여 나머지 제품을 검색할 수 있습니다.	아니요
`items`	`CollectionItemContractV8`	지정된 사용자에 대한 제품 배열입니다. 자세한 내용은 다음 표를 참조하세요.	아니요

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

Parameter	Type	Description	Required
`acquiredDate`	`datetime`	사용자가 항목을 획득한 날짜입니다.	예
`acquisitionType`	`string`	사용자가 이 자격을 얻은 방식을 나타냅니다. 자세한 내용은 제품 acquisitionType 값 및 의미를 참조하세요.	아니요
`devOfferId`	`string`	인앱 구매의 제안 ID입니다.	아니요
`endDate`	`datetime`	항목의 종료 날짜입니다.	예
`inAppOfferToken`	`string`	파트너 센터에서 항목에 할당된 개발자 지정 제품 ID 문자열입니다. 제품 ID의 예는 product123입니다.	아니요
`id`	`string`	사용자가 소유한 다른 항목에서 이 컬렉션 항목을 식별하는 ID입니다. 이 ID는 제품별로 고유합니다.	예
`legacyOfferInstanceId`	`string`	요청이 이전 XBOX Inventory Service에 있었던 경우 제공되는 `offerInstanceId` 값입니다. 대부분의 경우 필요하지 않습니다.	아니요
`legacyProductId`	`string`	XBOX Developer Portal의 이전 `ProductID` 형식이며 XBOX Inventory Service에서 사용됩니다. 파트너 센터에서 생성된 새 제품은 기본적으로 이 값을 가지지 않지만 필요한 경우 이 값을 갖도록 등록할 수 있습니다.	아니요
`localTicketReference`	`string`	요청 본문에서 이전에 제공된 `localTicketReference`의 ID입니다.	예
`modifiedDate`	`datetime`	이 항목이 마지막으로 수정된 날짜입니다. 소모품 제품의 경우 이 값은 다른 소모품 제품 구매를 통해 사용자의 수량 잔액이 변경되거나 소비 요청이 발행되면 변경됩니다.	예
`productFamily`	`string`	제품이 관련된 제품 유형을 나타냅니다. 일반적으로 “Games”이지만 게임 관련 콘텐츠의 경우 비어 있을 수도 있습니다.	아니요
`productId`	`string`	Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.	예
`productType`	`string`	제품 유형을 나타냅니다. 자세한 내용은 제품 유형 값 및 의미를 참조하세요.	예
`purchasedCountry`	`string`	제품이 획득된 지역 스토어를 나타내는 두 문자 ISO 3166 국가/지역 코드입니다.	아니요
`quantity`	`number`	항목의 수량입니다. 비소모품 제품은 항상 1입니다. 소모품 제품의 경우 이 값은 사용자가 소비하거나 이행할 수 있는 남은 잔액을 나타냅니다.	아니요
`satisfiedByProductIds`	`list<string>`	이 제품이 번들 또는 구독으로 인해 자격이 있는 경우 해당 상위 제품의 `ProductIds`가 여기에 제공됩니다. 참고: 요청 매개 변수 `filterSatisfiedByProductIds`를 `True`로 사용하면 이 매개 변수의 일부 결과가 누락됩니다.	아니요
`sharingSource`	`string`	항목이 공유 시나리오로 인해 자격이 있는지 여부를 나타냅니다. 그러나 서비스 간 호출의 경우 결과가 항상 직접 소유한 자격으로 범위가 지정되며 값은 항상 `None`으로 반환되어야 합니다.	아니요
`skuId`	`string`	Microsoft Store 카탈로그에 제품의 여러 제공 항목이 있는 경우의 특정 SKU 식별자입니다. SKU에 대한 스토어 ID의 예는 0010입니다.	예
`startDate`	`datetime`	항목이 유효해지는 날짜입니다.	예
`status`	`string`	항목의 상태입니다. 자세한 내용은 제품 상태 값 및 의미를 참조하세요.	예
`tags`	`string`	해당 없음.	예
`transactionId`	`GUID`	이 항목 구매의 결과인 트랜잭션 ID입니다. 항목을 이행된 것으로 보고하는 데 사용할 수 있습니다. 이 값은 사용자가 항목을 구매한 시점에 연결된 OrderID입니다. 이 사용자 자격의 고유 식별자로 사용해서는 안 됩니다.	아니요
`trialData`	`TrialInformation`	이 제품에 대한 정보 - 평가판인지와 남은 시간입니다.	예

TrialInformation 개체에는 다음 표에 나와 있는 매개 변수가 포함됩니다.

Parameter	Type	Description	Required
`isTrial`	`bool`	이 제품이 평가판을 통해 라이선스가 부여되었는지 여부를 나타냅니다.	예
`isInTrialPeriod`	`bool`	제품이 구독과 같은 평가판 기간에 있는지 여부를 나타냅니다.	예
`trialTimeRemaining`	`timespan`	평가판이 유효한 남은 시간을 DD:HH:MM:SS.MS 형식으로 나타냅니다.	아니요

제품 유형 값 및 의미

Value	Description
`Game`	기본 게임 제품 또는 게임 번들입니다.
`Application`	게임으로 나열되지 않은 Microsoft Store 내의 앱입니다.
`Durable`	한 번 구매하고 제품 종료 날짜까지 소유하는 다운로드 가능한 콘텐츠입니다. 또한 추가 기능 번들 및 시즌 패스 번들의 제품 유형입니다.
`Consumable`	사용자의 잔액(또는 수량)이 Collections 서비스에 보관되고 관리되는 스토어 관리 소모품입니다. 구매 시 수량이 사용자의 잔액에 추가되며 소비 요청을 수행하여 제거할 수 있습니다. 사용자는 먼저 이행되지 않아도 이 유형의 소모품을 다시 구매할 수 있습니다.
`UnmanagedConsumable`	개발자 관리 소모품이라고도 합니다. 사용자가 제품을 다시 구매할 수 있으려면 먼저 게임 또는 게임의 서비스에서 이행되어야 합니다.
`Pass`	스토어 관리 구독입니다. 파트너 센터에서 앱의 추가 기능 페이지 아래에 구성된 추가 기능 구독과는 다릅니다.

제품 상태 값 및 의미

Value	Description
`Active`	제품에 활성 자격이 있습니다. 사용자는 접근할 수 있어야 합니다.
`Revoked`	가장 일반적으로 사용자가 환불을 요청했음을 나타냅니다.
`Expired`	제품이 이후 만료된 자격(일반적으로 구독)의 일부였습니다.
`Banned`	해당 없음.
`Suspended`	해당 없음.

제품 acquisitionType 값 및 의미

Value	Description
`Single`	직접 디지털 구매 또는 코드 사용입니다.
`Recurring`	구독을 통해 소유하거나 자격이 있습니다.
`Conditional`	소유하지만 계속 사용하려면 다른 제품이 필요합니다. 예: Games With Gold로 획득한 게임

`satisfiedByProductIds` 필드로 만족된 자격의 결과 이해

satisfiedByProductIds 배열이 비어 있으면 사용자는 직접 구매를 통해 항목에 대한 직접 자격을 갖습니다. 그렇지 않고 satisfiedByProductIds 배열에 하나 이상의 ProductId가 있는 경우, 항목은 해당 제품(번들, 구독 등)에서 사용자에게 자격이 부여됩니다. 사용자가 항목에 대해 직접 자격과 만족시키는 자격을 모두 갖는 경우, 요청의 excludeDuplicates가 True이면 직접 자격이 우선하며 satisfiedByProductIds는 비어 있습니다.

응답 예제

HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:29:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1744
MS-CorrelationId: aadb976e-634e-4e63-92b1-93af49883b43
MS-RequestId: afeb8062-41e3-486e-b6c5-ec53a417bef3
MS-CV: BW/uJSvAbU6p3rbS.0
X-Content-Type-Options: nosniff

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "devOfferId": "",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "legacyOfferInstanceId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "legacyProductId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "purchasedCountry": "US",
            "productFamily": "",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "legacyOfferInstanceId": "4c584d39-3132-3058-c050-5757574b8500",
            "legacyProductId": "4c584d39-3132-3058-c050-5757574b8500",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "purchasedCountry": "US",
            "productFamily": "Games",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}

연속 토큰으로 나머지 결과 요청

쿼리에 단일 응답으로 반환할 수 있는 것보다 더 많은 결과가 있는 경우, 최신 응답에 continuationToken이 제공됩니다. 이 continuationToken을 이전 요청 본문의 복사본에 추가하여 후속 요청에 사용합니다. 예제:

POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

excludeDuplicates 플래그를 지정하더라도, 연속 토큰을 사용할 때는 상태가 다른 자격 항목을 얻을 수 있습니다. 따라서 중복 항목과 상태가 Active가 아닌 항목이 있는지 결과를 확인하세요.

참고 항목

서비스에서 제품 관리 Microsoft Store API로 서비스 인증 서비스에서 소모품 제품 관리 사용자 저장소 ID 키 갱신

​제품을 쿼리하는 데 b2bLicensePreview(Collections v8)와 publisherQuery(Collections v9) 비교

​요청

​필수 구성 요소

​요청 구문

​요청 헤더

​요청 본문

​요청 예제

​응답

​응답 본문

​제품 유형 값 및 의미

​제품 상태 값 및 의미

​제품 acquisitionType 값 및 의미

​satisfiedByProductIds 필드로 만족된 자격의 결과 이해

​응답 예제

​연속 토큰으로 나머지 결과 요청

​참고 항목

제품을 쿼리하는 데 b2bLicensePreview(Collections v8)와 publisherQuery(Collections v9) 비교

요청

필수 구성 요소

요청 구문

요청 헤더

요청 본문

요청 예제

응답

응답 본문

제품 유형 값 및 의미

제품 상태 값 및 의미

제품 acquisitionType 값 및 의미

`satisfiedByProductIds` 필드로 만족된 자격의 결과 이해

응답 예제

연속 토큰으로 나머지 결과 요청

참고 항목