查询产品Query for products

在 Microsoft Store 收集 API 中使用此方法,以获取客户在与你的 Azure AD 客户端 ID 相关联的应用中所拥有的所有产品。Use this method in the Microsoft Store collection API to get all the products that a customer owns for apps that are associated with your Azure AD client ID. 你可以将查询范围设置为特定产品,或使用其他筛选器。You can scope your query to a particular product, or use other filters.

此方法旨在由你的服务调用,用于响应来自你的应用的消息。This method is designed to be called by your service in response to a message from your app. 你的服务不应定期按计划轮询所有用户。Your service should not regularly poll for all users on a schedule.

先决条件Prerequisites

若要使用此方法,你需要:To use this method, you will need:

  • 受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • 一个 Microsoft Store ID 密钥,表示要获得其产品的用户的身份。A Microsoft Store ID key that represents the identity of the user whose products you want to get.

有关详细信息,请参阅管理来自服务的产品授权For more information, see Manage product entitlements from a service.

请求Request

请求语法Request syntax

方法Method 请求 URIRequest URI
POSTPOST https://collections.mp.microsoft.com/v6.0/collections/query

请求标头Request header

标头Header 类型Type 说明Description
授权Authorization 字符串string 必需。Required. Azure AD 访问令牌的格式为 Bearer <token>。The Azure AD access token in the form Bearer <token>.
HostHost 字符串string 必须设置为值 collections.mp.microsoft.comMust be set to the value collections.mp.microsoft.com.
Content-LengthContent-Length 数字number 请求正文的长度。The length of the request body.
Content-TypeContent-Type 字符串string 指定请求和响应类型。Specifies the request and response type. 当前,唯一受支持的值为 application/jsonCurrently, the only supported value is application/json.

请求正文Request body

参数Parameter 类型Type 说明Description 必需Required
受益人beneficiaries UserIdentityUserIdentity 表示要为产品查询的用户的 UserIdentity 对象。A UserIdentity object that represents the user being queried for products. 有关详细信息,请参阅下表。For more information, see the table below. Yes
ContinuationTokencontinuationToken 字符串string 如果有多组产品,响应正文将在达到页面限制时返回延续令牌。If there are multiple sets of products, the response body returns a continuation token when the page limit is reached. 在后续调用中提供此处的延续令牌以检索剩余 产品。Provide that continuation token here in subsequent calls to retrieve remaining products. No
MaxPageSizemaxPageSize 数字number 要在一次响应中返回的最大产品数。The maximum number of products to return in one response. 默认值和最大值为 100。The default and maximum value is 100. No
ModifiedAftermodifiedAfter 日期/时间datetime 如果已指定,该服务仅返回已在此日期后修改的产品。If specified, the service only returns products that have been modified after this date. No
ParentProductIDparentProductId 字符串string 如果已指定,该服务仅返回对应于指定应用的加载项。If specified, the service only returns add-ons that correspond to the specified app. No
productSkuIdsproductSkuIds list<ProductSkuId>list<ProductSkuId> 如果已指定,该服务仅返回适用于所提供的产品/SKU 对的产品。If specified, the service only returns products applicable to the provided product/SKU pairs. 有关详细信息,请参阅下表。For more information, see the table below. No
ProductTypeproductTypes 字符串string 如果已指定,该服务仅返回与指定产品类型匹配的产品。If specified, the service only returns products that match the specified product types. 受支持的产品类型为 ApplicationDurableUnmanagedConsumableSupported product types are Application, Durable, and UnmanagedConsumable. No
ValidityTypevalidityType 字符串string 当设置为 All 时,将返回用户的所有产品,包括已过期的项目。When set to All, all products for a user will be returned, including expired items. 当设置为 Valid 时,仅返回在此时有效的产品(即,它们的状态为活动,开始日期 < 现在,结束日期 > 现在)。When set to Valid, only products that are valid at this point in time are returned (that is, they have an active status, start date < now, and end date is > now). 不支持No

UserIdentity 对象包含以下参数。The UserIdentity object contains the following parameters.

参数Parameter 类型Type 说明Description 必需Required
IdentityTypeidentityType 字符串string 指定字符串值 b2bSpecify the string value b2b. Yes
identityValueidentityValue stringstring Microsoft Store ID 密钥,表示要查询其产品的用户的身份。The Microsoft Store ID key that represents the identity of the user for whom you want to query products. Yes
localTicketReferencelocalTicketReference 字符串string 已返回产品的请求标识符。The requested identifier for the returned products. 响应正文中返回的项目将具有匹配的 localTicketReferenceReturned items in the response body will have a matching localTicketReference. 建议使用与 Microsoft Store ID 密钥中的 userId 声明相同的值。We recommend that you use the same value as the userId claim in the Microsoft Store ID key. Yes

ProductSkuId 对象包含以下参数。The ProductSkuId object contains the following parameters.

参数Parameter 类型Type 说明Description 必需Required
productIdproductId stringstring Microsoft Store 目录中的产品Store IDThe Store ID for a product in the Microsoft Store catalog. 产品的示例应用商店 ID 为 9NBLGGH42CFD。An example Store ID for a product is 9NBLGGH42CFD. Yes
SkuIDskuID stringstring Microsoft Store 目录中的产品 SKUStore IDThe Store ID for a product's SKU in the Microsoft Store catalog. SKU 的示例应用商店 ID 为 0010。An example Store ID for a SKU is 0010. Yes

请求示例Request example

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"
}

响应Response

响应正文Response body

参数Parameter 类型Type 说明Description 必需Required
ContinuationTokencontinuationToken 字符串string 如果有多组产品,此令牌将在达到页面限制时返回。If there are multiple sets of products, this token is returned when the page limit is reached. 你可以在后续调用中指定此延续令牌以检索剩余 产品。You can specify this continuation token in subsequent calls to retrieve remaining products. No
项目items CollectionItemContractV6CollectionItemContractV6 指定用户的一组产品。An array of products for the specified user. 有关详细信息,请参阅下表。For more information, see the table below. No

CollectionItemContractV6 对象包含以下参数。The CollectionItemContractV6 object contains the following parameters.

参数Parameter 类型Type 说明Description 必需Required
AcquiredDateacquiredDate 日期/时间datetime 用户获取该项目的日期。The date on which the user acquired the item. Yes
campaignIdcampaignId 字符串string 在购买时为此项目提供的市场活动 ID。The campaign ID that was provided at purchase time for this item. No
devOfferIddevOfferId 字符串string 应用内购买的优惠 ID。The offer ID from an in-app purchase. No
EndDateendDate 日期/时间datetime 项目的结束日期。The end date of the item. Yes
FulfillmentDatafulfillmentData 字符串string 不适用N/A No
InAppOfferTokeninAppOfferToken 字符串string 开发人员指定的产品 ID 字符串,该字符串已分配给 Windows 开发人员中心仪表板中的项目。The developer-specified product ID string that is assigned to the item in the Windows Dev Center dashboard. 示例产品 ID 为 product123An example product ID is product123. No
ItemIDitemId 字符串string 用于从用户所拥有的其他项目标识此集合项 的 ID。An ID that identifies this collection item from other items the user owns. 此 ID 对于每个产品都是唯一的。This ID is unique per product. Yes
localTicketReferencelocalTicketReference stringstring 请求正文中上次提供的 localTicketReference 的 ID。The ID of the previously supplied localTicketReference in the request body. Yes
ModifiedDatemodifiedDate 日期/时间datetime 最后修改此项目的日期。The date this item was last modified. Yes
orderIdorderId 字符串string 获取此项目的顺序 ID(如果存在)。If present, the order ID of which this item was obtained. No
orderLineItemIdorderLineItemId 字符串string 获取此项目的特定顺序的行项(如果存在) 。If present, the line item of the particular order for which this item was obtained. No
OwnershipTypeownershipType stringstring 字符串 OwnedByBeneficiaryThe string OwnedByBeneficiary. Yes
productIdproductId stringstring Microsoft Store 目录中的产品Store IDThe Store ID for the product in the Microsoft Store catalog. 产品的示例应用商店 ID 为 9NBLGGH42CFD。An example Store ID for a product is 9NBLGGH42CFD. Yes
productTypeproductType 字符串string 以下产品类型之一:ApplicationDurableUnmanagedConsumableOne of the following product types: Application, Durable, and UnmanagedConsumable. Yes
PurchasedCountrypurchasedCountry 字符串string 不适用N/A No
购买者purchaser IdentityContractV6IdentityContractV6 这表示项目的购买者的标识(如果存在)。If present, this represents the identity of the purchaser of the item. 请参阅下面有关此对象的详细信息。See the details for this object below. No
quantityquantity 数字number 项目的数量。The quantity of the item. 当前,这将始终为 1。Currently, this will always be 1. No
skuIdskuId stringstring Microsoft Store 目录中的产品 SKUStore IDThe Store ID for the product's SKU in the Microsoft Store catalog. SKU 的示例应用商店 ID 为 0010。An example Store ID for a SKU is 0010. Yes
SkuTypeskuType 字符串string SKU 的类型。Type of the SKU. 可能的值包括 TrialFullRentalPossible values include Trial, Full, and Rental. Yes
StartDatestartDate 日期/时间datetime 项目开始有效的日期。The date that the item starts being valid. Yes
statusstatus 字符串string 项目的状态。The status of the item. 可能的值包括 ActiveExpiredRevokedBannedPossible values include Active, Expired, Revoked, and Banned. Yes
tagstags 字符串string 不适用N/A Yes
transactionIdtransactionId guidguid 因购买此项目而产生的事务 ID。The transaction ID as a result of the purchase of this item. 可 用于将项目报告为已完成。Can be used for reporting an item as fulfilled. Yes

IdentityContractV6 对象包含以下参数。The IdentityContractV6 object contains the following parameters.

参数Parameter 类型Type 说明Description 必需Required
IdentityTypeidentityType stringstring 包含值 pubContains the value pub. Yes
identityValueidentityValue 字符串string 指定的 Microsoft Store ID 密钥的 publisherUserId 字符串值。The string value of the publisherUserId from the specified Microsoft Store ID key. Yes

响应示例Response example

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"
    }
  ]
}