查询产品

项目
06/25/2024

在 Microsoft Store 收集 API 中使用此方法，以获取客户在与你的 Azure AD 客户端 ID 相关联的应用中所拥有的所有产品。你可以将查询范围设置为特定产品，或使用其他筛选器。

此方法旨在由你的服务调用，用于响应来自你的应用的消息。你的服务不应定期按计划轮询所有用户。

Microsoft.StoreServices 库通过 StoreServicesClient.CollectionsQueryAsync API 提供此方法的功能。

先决条件

若要使用此方法，你需要：

受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。
一个 Microsoft Store ID 密钥，表示要获得其产品的用户的身份。

有关详细信息，请参阅管理来自服务的产品授权。

请求

请求语法

方法	请求 URI
POST	`https://collections.mp.microsoft.com/v6.0/collections/query`

请求头

标头	类型	说明
授权	字符串	必需。 Azure AD 访问令牌的格式为 Bearertoken<>。
主机	string	必须设置为值 collections.mp.microsoft.com。
Content-Length	数值	请求正文的长度。
Content-Type	字符串	指定请求和响应类型。当前，唯一受支持的值为 application/json。

请求正文

参数	类型	描述	必须
受益人	list<UserIdentity>	代表正在查询产品的用户的 UserIdentity 对象列表。有关详细信息，请参阅下表。	是
continuationToken	string	如果有多组产品，响应正文将在达到页面限制时返回延续令牌。在后续调用中提供此处的延续令牌以检索剩余产品。	否
MaxPageSize	数值	要在一次响应中返回的最大产品数。默认值和最大值为 100。	否
ModifiedAfter	datetime	如果已指定，该服务仅返回已在此日期后修改的产品。	否
parentProductId	string	如果已指定，该服务仅返回对应于指定应用的加载项。	否
productSkuIds	list<ProductSkuId>	如果已指定，该服务仅返回适用于所提供的产品/SKU 对的产品。有关详细信息，请参阅下表。	否
ProductType	list<string>	指定要在查询结果中返回的产品类型。受支持的产品类型为 Application、Durable、Game 和 UnmanagedConsumable。	是
ValidityType	string	当设置为 All 时，将返回用户的所有产品，包括已过期的项目。当设置为 Valid 时，仅返回在此时有效的产品（即，它们的状态为活动，开始日期 < 现在，结束日期 > 现在）。	否

UserIdentity 对象包含以下参数。

参数	类型	描述	必须
IdentityType	string	指定字符串值 b2b。	是
identityValue	string	Microsoft Store ID 密钥，表示要查询其产品的用户的身份。	是
localTicketReference	string	已返回产品的请求标识符。响应正文中返回的项目将具有匹配的 localTicketReference。建议使用与 Microsoft Store ID 密钥中的 userId 声明相同的值。	是

ProductSkuId 对象包含以下参数。

参数	类型	描述	必须
productId	string	Microsoft Store 目录中的产品的 Store ID。产品的示例应用商店 ID 为 9NBLGGH42CFD。	是
skuId	string	Microsoft Store 目录中的产品 SKU 的 Store ID。 SKU 的示例应用商店 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	如果有多组产品，此令牌将在达到页面限制时返回。你可以在后续调用中指定此延续令牌以检索剩余产品。	否
items	CollectionItemContractV6	指定用户的一组产品。有关详细信息，请参阅下表。	否

CollectionItemContractV6 对象包含以下参数。

参数	类型	描述	必须
AcquiredDate	datetime	用户获取该项目的日期。	是
campaignId	string	在购买时为此项目提供的市场活动 ID。	否
devOfferId	string	应用内购买的优惠 ID。	否
endDate	datetime	项目的结束日期。	是
FulfillmentData	list<string>	空值	否
InAppOfferToken	string	开发人员指定的产品 ID 字符串，该字符串已分配给合作伙伴中心中的项目。产品 ID 示例为 product123。	否
itemId	string	用于从用户所拥有的其他项目标识此集合项的 ID。此 ID 对于每个产品都是唯一的。	是
localTicketReference	string	请求正文中上次提供的 localTicketReference 的 ID。	是
ModifiedDate	datetime	最后修改此项目的日期。	是
orderId	string	获取此项目的顺序 ID（如果存在）。	否
orderLineItemId	string	获取此项目的特定顺序的行项（如果存在）。	否
OwnershipType	string	字符串 OwnedByBeneficiary。	是
productId	string	Microsoft Store 目录中的产品的 Store ID。产品的示例应用商店 ID 为 9NBLGGH42CFD。	是
productType	string	以下产品类型之一：Application、Durable 和 UnmanagedConsumable。	是
PurchasedCountry	string	空值	否
购买者	IdentityContractV6	这表示项目的购买者的标识（如果存在）。请参阅下面有关此对象的详细信息。	否
quantity	数值	项目的数量。当前，这将始终为 1。	否
skuId	string	Microsoft Store 目录中的产品 SKU 的 Store ID。 SKU 的示例应用商店 ID 为 0010。	是
SkuType	string	SKU 的类型。可能的值包括 Trial、Full 和 Rental。	是
startDate	datetime	项目开始有效的日期。	是
状态	string	项状态。可能的值包括 Active、Expired、Revoked 和 Banned。	是
标记	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: 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"
    }
  ]
}

通过

查询产品

先决条件

请求

请求语法

请求头

请求正文

请求示例

响应

响应正文

响应示例

反馈

其他资源

通过

查询产品

先决条件

请求

请求语法

请求头

请求正文

请求示例

响应

响应正文

响应示例

相关主题

反馈

其他资源