제품에 대한 쿼리

  • 아티클

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

요청 헤더

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

요청 본문

매개 변수 형식 설명 필수
수혜자 list<UserIdentity> 제품에 대해 쿼리 중인 사용자를 나타내는 UserIdentity 개체의 목록입니다. 자세한 내용은 아래 표를 참조하세요. 예
continuationToken string 제품 집합이 여러 개 있는 경우, 페이지 제한에 도달할 때 응답 본문이 연속 토큰을 반환합니다. 나머지 제품을 검색하는 후속 호출에서 그 연속 토큰을 지정합니다. 아니요
maxPageSize number 하나의 응답에 반환하는 제품의 최대 수입니다. 기본 및 최대 값은 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 string Microsoft Store 카탈로그의 제품에 대한 Microsoft Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다. 예
productType string 다음 제품 유형 중 하나입니다. Application, Durable 및 UnmanagedConsumable. 예
purchasedCountry string 해당 없음 아니요
구매자 IdentityContractV6 있는 경우 항목의 구매자 ID를 나타냅니다. 이 개체에 대한 자세한 내용은 아래를 참조하세요. 아니요
quantity number 품목의 수량입니다. 현재는 항상 1입니다. 아니요
skuId string Microsoft Store 카탈로그의 제품 SKU에 대한 Microsoft Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다. 예
skuType string SKU의 형식입니다. 가능한 값은 평가판, 전체 및 임대입니다. 예
startDate 날짜/시간 품목이 유효한 시작 날짜입니다. 예
상태 string 품목의 상태입니다. 가능한 값에는 활성, 만료됨, 해지됨 및 금지됨이 포함됩니다. 예
tags list<string> 해당 없음 예
transactionId guid 이 품목의 구매 결과인 트랜잭션 ID입니다. 품목을 처리됨으로 보고하는 데 사용할 수 있습니다. 예

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

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

응답 예제

HTTP/1.1 200 OK
Content-Length: 7241
Content-Type: application/json
MS-CorrelationId: 699681ce-662c-4841-920a-f2269b2b4e6c
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"
    }
  ]
}