collections.mp.microsoft.com/v9.0/collections/publisherQuery

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

publisherQuery는 파트너 서비스의 호출만 지원합니다.

클라이언트 앱 또는 게임은 이 서비스를 직접 호출할 수 없습니다.

publisherQuery(Collections Query v9)의 업데이트 및 개선 사항

publisherQuery는 최신 Collections Query API(v9)입니다. b2bLicensePreview(v8)에서 마이그레이션하는 경우 이 섹션에서 동작 차이점을 검토하세요. publisherQuery는 b2bLicensePreview에 비해 다음과 같은 변경 사항과 개선 사항이 있습니다.

사용자의 XBOX Game Pass 구독 상태를 쿼리할 수 있는 기능
반환할 미리 정의된 제품 목록이 필요합니다. 모범 사례이지만 v8 b2bLicensePreview에서는 필수가 아니었습니다. 이 모범 사례를 따르지 않은 타이틀은 종종 출시 후 쿼리 매개 변수를 기반으로 하는 콘텐츠의 큰 범위로 인해 요청이 시간 초과되는 문제를 겪었습니다. 이는 게임의 서비스가 쿼리 요청 내에서 원하는 ProductId를 지정하도록 업데이트될 때까지 사용자가 게임 내 크레딧을 얻지 못하게 했습니다.
사용되지 않거나 불필요한 값을 제거하도록 응답 데이터 필드를 간소화했습니다.
개발자 피드백을 기반으로 요청 매개 변수를 간소화했습니다.

요청 본문에서 제거됨:

Market - publisherQuery에서 모든 요청은 모든 지역에 대한 컨텍스트를 가집니다.
ExpandSatisfyingItems - publisherQuery에서 모든 결과는 만족시키는 자격을 확장합니다.
EntitlementsFilter - 쿼리의 미리 정의된 productIds 목록이 필요하기 때문에 사용되지 않습니다.

publisherQuery는 LegacyProductIds(더 이상 사용되지 않는 XBOX Developer Portal에서 생성되어 XBOX Inventory 서비스의 ProductId로 사용된 ProductIds)를 지원하지 않습니다.

XBOX Inventory에서 서비스를 마이그레이션하는 경우 자체 서비스에서 StoreId(Collections의 ProductId 값)를 일치하는 LegacyProductId에 내부적으로 매핑해야 합니다. 그렇지 않으면 StoreId와 LegacyProductIds를 모두 반환하는 v8 b2bLicensePreview를 볼 수 있습니다. 자세한 내용은 관련 문서 필요에 맞는 올바른 Collections 쿼리 API 선택을 참조하세요.

필수 구성 요소

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

요청

요청 구문

Method	Request URI
`POST`	`https://collections.mp.microsoft.com/v9.0/collections/publisherQuery`

요청 헤더

Header	Type	Description
`Authorization`	`string`	필수. 사용 중인 인증 유형에 따라 위임된 권한 부여 X-token 또는 Microsoft Entra ID 서비스 액세스 토큰 중 하나입니다.
`Signature`	`string`	X-token으로 인증할 때 필수입니다.
`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>`	대상 제품 목록입니다. 자세한 내용은 다음 표를 참조하세요. v9 publisherQuery API는 요청당 최대 100개의 productSkuIds를 지원합니다.	예
`continuationToken`	`string`	`maxPageSize` 내에 맞지 않는 여러 제품 세트가 있는 경우, 페이지 제한에 도달하면 응답 본문에 연속 토큰이 반환됩니다. 더 많은 결과를 얻으려면 후속 호출에서 연속 토큰을 제공하세요.	아니요
`maxPageSize`	`number`	한 응답에서 반환할 최대 제품 수입니다. 기본값은 100이며 최대값은 페이지당 200개 항목입니다.	아니요
`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입니다.	아니요

요청 예제

v9 publisherQuery API는 요청당 최대 100개의 productSkuIds를 지원합니다. productSkuIds에 100개보다 많은 productIds를 제공하면 API가 HTTP 400 오류를 반환합니다.

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

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

응답

응답 본문

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

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

Parameter	Type	Description	Required
`acquiredDate`	`datetime`	사용자가 항목을 획득한 날짜입니다.	예
`acquisitionType`	`string`	사용자가 이 자격을 얻은 방식을 나타냅니다. 자세한 내용은 제품 acquisitionType 값 및 의미를 참조하세요.	아니요
`endDate`	`datetime`	항목의 종료 날짜입니다.	예
`id`	`string`	사용자가 소유한 다른 항목에서 이 컬렉션 항목을 식별하는 ID입니다. 이 ID는 제품별로 고유합니다.	예
`modifiedDate`	`datetime`	이 항목이 마지막으로 수정된 날짜입니다. 소모품 제품의 경우 이 값은 다른 소모품 제품 구매를 통해 사용자의 수량 잔액이 변경되거나 소비 요청이 발행되면 변경됩니다.	예
`productId`	`string`	Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.	예
`productKind`	`string`	제품 유형을 나타냅니다. 자세한 내용은 제품 유형 값 및 의미를 참조하세요.	예
`quantity`	`number`	항목의 수량입니다. 비소모품 제품은 항상 1입니다. 소모품 제품의 경우 값은 사용자가 소비하거나 이행할 수 있는 남은 잔액을 나타냅니다.	아니요
`recurrenceData`	`string`	반복 관리 API의 `recurrenceId` 매개 변수로 사용되는 항목의 ID입니다. RecurrenceQuery API의 `id` 및 Clawback 이벤트의 `recurrenceId`와 동일한 값입니다.	예
`satisfiedByProductIds`	`list<string>`	이 제품이 번들 또는 구독으로 인해 자격이 있는 경우 해당 상위 제품의 `ProductIds`가 여기에 제공됩니다. 참고: 요청 매개 변수 `filterSatisfiedByProductIds`를 `True`로 사용하면 이 매개 변수의 일부 결과가 누락됩니다.	아니요
`skuId`	`string`	Microsoft Store 카탈로그에 제품의 여러 제공 항목이 있는 경우의 특정 SKU 식별자입니다. SKU에 대한 스토어 ID의 예는 0010입니다.	예
`startDate`	`datetime`	항목이 유효해지는 날짜입니다.	예
`status`	`string`	항목의 상태입니다. 자세한 내용은 제품 상태 값 및 의미를 참조하세요.	예
`tags`	`list<string>`	해당 없음.	예
`transactionId`	`GUID`	이 항목 구매의 결과인 트랜잭션 ID입니다. 항목을 이행된 것으로 보고하는 데 사용할 수 있습니다. 이 값은 사용자가 항목을 구매한 시점에 연결된 OrderID입니다. 이 사용자 자격의 고유 식별자로 사용해서는 안 됩니다.	아니요
`trialData`	`TrialInformation`	이 제품에 대한 정보 - 평가판인지와 남은 시간입니다.	예

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

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

제품 유형 값 및 의미

Value	Description
`Application`	게임으로 나열되지 않은 Microsoft Store 내의 앱입니다.
`Consumable`	사용자의 잔액(또는 수량)이 Collections 서비스에 보관되고 관리되는 스토어 관리 소모품입니다. 구매 시 수량이 사용자의 잔액에 추가되며 소비 요청을 수행하여 제거할 수 있습니다. 사용자는 먼저 이행되지 않아도 이 유형의 소모품을 다시 구매할 수 있습니다.
`Durable`	한 번 구매하고 제품 종료 날짜까지 소유하는 다운로드 가능한 콘텐츠입니다. 또한 추가 기능 번들 및 시즌 패스 번들의 제품 유형입니다.
`Game`	기본 게임 제품입니다.
`Pass`	Game Pass와 같은 일부 구독 유형입니다.
`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:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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"
            }
        }
    ]
}

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

쿼리에 단일 응답으로 반환할 수 있는 것보다 더 많은 결과가 있는 경우(maxPageSize로 제어됨), 초기 쿼리 응답에 continuationToken이 포함됩니다. 그런 다음 이전 요청 본문의 복사본에 연속 토큰을 추가하여 후속 요청에서 이 continuationToken을 사용할 수 있습니다. 연속 요청 예제:

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

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

참고 항목

서비스에서 제품 관리 Microsoft Store API로 서비스 인증 서비스에서 소모품 제품 관리

​publisherQuery(Collections Query v9)의 업데이트 및 개선 사항

​필수 구성 요소

​요청

​요청 구문

​요청 헤더

​요청 본문

​요청 예제

​응답

​응답 본문

​제품 유형 값 및 의미

​제품 상태 값 및 의미

​제품 acquisitionType 값 및 의미

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

​응답 예제

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

​참고 항목

publisherQuery(Collections Query v9)의 업데이트 및 개선 사항

필수 구성 요소

요청

요청 구문

요청 헤더

요청 본문

요청 예제

응답

응답 본문

제품 유형 값 및 의미

제품 상태 값 및 의미

제품 acquisitionType 값 및 의미

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

응답 예제

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

참고 항목