제품에 대한 쿼리 보내기

아티클
06/25/2024

Microsoft Store 컬렉션 API에서 이 메서드를 사용하여 Azure AD 클라이언트 ID와 연관된 앱에 대해 고객이 소유한 모든 제품을 가져옵니다. 쿼리 범위를 특정 제품으로 지정하거나 다른 필터를 사용할 수 있습니다.

이 메서드는 앱의 메시지에 대한 응답으로 서비스에서 호출하도록 설계되었습니다. 서비스가 일정에 따라 모든 사용자를 정기적으로 폴링해서는 안 됩니다.

Microsoft.StoreServices 라이브러리는 StoreServicesClient.CollectionsQueryAsync API를 통해 이 메서드의 기능을 제공합니다.

필수 조건

이 메서드를 사용하려면 다음이 필요합니다.

대상 URI 값이 https://onestore.microsoft.com인 Azure AD 액세스 토큰입니다.
가져오려는 제품을 소유한 사용자의 ID를 나타내는 Microsoft Store ID 키

자세한 정보는 서비스에서 제품 권리 유형 관리하기를 참조하세요.

요청

요청 구문

메서드	요청 URI
게시	`https://collections.mp.microsoft.com/v6.0/collections/query`

요청 헤더

헤더	형식	설명
권한 부여	string	필수. Bearer<토큰> 형식의 Azure AD 액세스 토큰.
Host	string	collections.mp.microsoft.com 값으로 설정해야 합니다.
Content-Length	수	요청 본문의 길이입니다.
Content-Type	문자열	요청 및 응답 형식을 지정합니다. 현재 유일하게 지원되는 값은 application/json입니다.

요청 본문

매개 변수	형식	설명	필수
수혜자	list<UserIdentity>	제품에 대해 쿼리 중인 사용자를 나타내는 UserIdentity 개체의 목록입니다. 자세한 내용은 아래 표를 참조하세요.	예
continuationToken	string	제품 집합이 여러 개 있는 경우, 페이지 제한에 도달할 때 응답 본문이 연속 토큰을 반환합니다. 나머지 제품을 검색하는 후속 호출에서 그 연속 토큰을 지정합니다.	아니요
maxPageSize	번호	하나의 응답에 반환하는 제품의 최대 수입니다. 기본 및 최대 값은 100입니다.	아니요
modifiedAfter	날짜/시간	지정된 경우 서비스는 이 날짜 이후에 수정된 제품만 반환합니다.	아니요
parentProductId	string	지정된 경우 서비스는 지정된 앱에 해당하는 추가 기능만 반환합니다.	아니요
productSkuIds	list<ProductSkuId>	지정한 경우 서비스는 제공된 제품/SKU 쌍에 해당하는 제품만 반환합니다. 자세한 내용은 아래 표를 참조하세요.	아니요
productTypes	list<string>	쿼리 결과에 반환할 제품 유형을 지정합니다. 지원되는 제품 유형은 Application, Durable, Game 및 UnmanagedConsumable입니다.	예
validityType	string	모두로 설정되면 만료된 항목을 포함하여 사용자에 대한 모든 제품이 반환됩니다. Valid로 설정하면 이 시점에서 유효한 제품만 반환됩니다(즉, 활성 상태, 시작일 < 현재, 종료일 > 현재인 경우).	아니요

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

매개 변수	형식	설명	필수
identityType	string	문자열 값 b2b를 지정합니다.	예
identityValue	string	제품을 쿼리하려는 사용자의 ID를 나타내는 Microsoft Store ID 키입니다.	예
localTicketReference	string	반환된 제품에 대해 요청된 식별자입니다. 응답 본문에서 반환된 항목에는 일치하는 localTicketReference가 있습니다. Microsoft Store ID 키의 userId 클레임과 동일한 값을 사용하는 것이 좋습니다.	예

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

매개 변수	형식	설명	필수
productId	string	Microsoft Store 카탈로그의 제품에 대한 Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다.	예
skuId	string	Microsoft Store 카탈로그의 제품 SKU에 대한 Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다.	예

요청 예시

POST https://collections.mp.microsoft.com/v6.0/collections/query HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Q…….
Host: collections.mp.microsoft.com
Content-Length: 2531
Content-Type: application/json

{
  "maxPageSize": 100,
  "beneficiaries": [
    {
      "localTicketReference": "1055521810674918",
      "identityValue": "eyJ0eXAiOiJ……",
      "identityType": "b2b"
    }
  ],
  "modifiedAfter": "\/Date(-62135568000000)\/",
  "productSkuIds": [
    {
      "productId": "9NBLGGH5WVP6",
      "skuId": "0010"
    }
  ],
  "productTypes": [
    "UnmanagedConsumable"
  ],
  "validityType": "All"
}

응답

응답 본문

매개 변수	형식	설명	필수
continuationToken	string	제품 집합이 여러 개인 경우 페이지 제한에 도달할 때 이 토큰이 반환됩니다. 나머지 제품을 검색하는 후속 호출에서 그 연속 토큰을 지정할 수 있습니다.	아니요
항목	CollectionItemContractV6	사용자가 지정된 제품의 배열입니다. 자세한 내용은 아래 표를 참조하세요.	아니요

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

매개 변수	형식	설명	필수
acquiredDate	날짜/시간	사용자가 품목을 획득한 날짜입니다.	예
campaignId	string	이 항목에 대한 구매 시 제공된 캠페인 ID입니다.	아니요
devOfferId	string	앱에서 바로 구매 시 제공되는 ID입니다.	아니요
endDate	날짜/시간	품목의 종료 날짜입니다.	예
fulfillmentData	list<string>	해당 없음	아니요
inAppOfferToken	string	파트너 센터에서 항목에 할당되는 개발자가 지정한 제품 ID 문자열입니다. 제품 ID의 예는 product123입니다.	아니요
itemId	string	사용자가 소유한 다른 항목에서 이 컬렉션 항목을 식별하는 ID입니다. 이 ID는 제품마다 고유합니다.	예
localTicketReference	string	요청 본문에서 이전에 제공된 localTicketReference의 ID입니다.	예
modifiedDate	날짜/시간	이 품목을 마지막으로 수정한 날짜입니다.	예
orderId	string	있는 경우 이 항목을 가져온 주문 ID입니다.	아니요
orderLineItemId	string	있는 경우 이 항목을 가져온 특정 순서의 품목입니다.	아니요
ownershipType	string	문자열 OwnedByBeneficiary입니다.	예
productId	문자열	Microsoft Store 카탈로그의 제품에 대한 Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다.	예
productType	string	다음 제품 유형 중 하나입니다. Application, Durable 및 UnmanagedConsumable.	예
purchasedCountry	string	해당 없음	아니요
구매자	IdentityContractV6	있는 경우 항목의 구매자 ID를 나타냅니다. 이 개체에 대한 자세한 내용은 아래를 참조하세요.	아니요
quantity	번호	품목의 수량입니다. 현재는 항상 1입니다.	아니요
skuId	문자열	Microsoft Store 카탈로그의 제품 SKU에 대한 Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다.	예
skuType	string	SKU의 형식입니다. 가능한 값은 평가판, 전체 및 임대입니다.	예
startDate	날짜/시간	품목이 유효한 시작 날짜입니다.	예
상태	string	품목의 상태입니다. 가능한 값에는 활성, 만료됨, 해지됨 및 금지됨이 포함됩니다.	예
tags	list<string>	해당 없음	예
transactionId	guid	이 품목의 구매 결과인 트랜잭션 ID입니다. 품목을 처리됨으로 보고하는 데 사용할 수 있습니다.	예

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

매개 변수	형식	설명	필수
identityType	string	pub 값을 포함합니다.	예
identityValue	문자열	지정된 Microsoft Store ID 키에 있는 publisherUserId의 문자열 값입니다.	예

응답 예시

HTTP/1.1 200 OK
Content-Length: 7241
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: a9988cf9-652b-4791-beba-b0e732121a12
MS-CV: xu2HW6SrSkyfHyFh.0.1
MS-ServerId: 020022359
Date: Tue, 22 Sep 2015 20:28:18 GMT

{
  "items" : [
    {
      "acquiredDate" : "2015-09-22T19:22:51.2068724+00:00",
      "devOfferId" : "f9587c53-540a-498b-a281-8a349491ed47",
      "endDate" : "9999-12-31T23:59:59.9999999+00:00",
      "fulfillmentData" : [],
      "inAppOfferToken" : "consumable2",
      "itemId" : "4b8fbb13127a41f299270ea668681c1d",
      "localTicketReference" : "1055521810674918",
      "modifiedDate" : "2015-09-22T19:22:51.2513155+00:00",
      "orderId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31",
      "ownershipType" : "OwnedByBeneficiary",
      "productId" : "9NBLGGH5WVP6",
      "productType" : "UnmanagedConsumable",
      "purchaser" : {
        "identityType" : "pub",
        "identityValue" : "user123"
      },
      "skuId" : "0010",
      "skuType" : "Full",
      "startDate" : "2015-09-22T19:22:51.2068724+00:00",
      "status" : "Active",
      "tags" : [],
      "transactionId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31"
    }
  ]
}

다음을 통해 공유

제품에 대한 쿼리 보내기

필수 조건

요청

요청 구문

요청 헤더

요청 본문

요청 예시

응답

응답 본문

응답 예시

피드백

추가 리소스

다음을 통해 공유

제품에 대한 쿼리 보내기

필수 조건

요청

요청 구문

요청 헤더

요청 본문

요청 예시

응답

응답 본문

응답 예시

관련 항목

피드백

추가 리소스