查詢產品

在 Microsoft Store 集合 API 中使用此方法，以取得客戶所擁有的所有產品，以取得與您 Azure AD 用戶端識別碼相關聯的應用程式。 您可以將查詢的範圍設定為特定產品，或使用其他篩選條件。

這個方法的設計目的是要由您的服務呼叫，以回應來自您應用程式的訊息。 您的服務不應依排程定期輪詢所有使用者。

Microsoft.StoreServices 程式庫透過 StoreServicesClient.CollectionsQueryAsync 提供此方法的功能。

必要條件

若要使用此方法，您將需要：

• Azure AD 存取權杖，具有對象 URI 值 https://onestore.microsoft.com。
• Microsoft Store ID 金鑰，代表您要取得其產品的使用者身分識別。

如需詳細資訊，請參閱從服務管理產品權利。

Request

要求語法

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

要求標頭

標題	類型	描述
授權	字串	必要。 持有人<權杖>形式的 Azure AD 存取權杖。
Host	字串	必須設定為值 collections.mp.microsoft.com。
Content-Length	值	要求本文的長度。
內容-類型	字串	指定要求和回應類型。 目前唯一支援的值是 application/json。

要求本文

參數	類型	描述	必要
beneficiaries	list<UserIdentity>	UserIdentity 物件的清單，代表要查詢產品的使用者。 如需詳細資訊，請參閱下列資料表。	Yes
continuationToken	字串	如果有多個產品集，當達到頁面限制時，回應本文會傳回接續權杖。 在後續呼叫中提供該接續權杖，以擷取剩餘的產品。	No
maxPageSize	數值	在一個回應中傳回的產品數目上限。 預設值和最大值為 100。	No
modifiedAfter	Datetime	如果指定，服務只會傳回在此日期之後修改的產品。	No
parentProductId	字串	如果指定，服務只會傳回對應至指定應用程式的附加元件。	No
productSkuIds	list<ProductSkuId>	如果指定，服務只會傳回適用於所提供產品/SKU 組的產品。 如需詳細資訊，請參閱下列資料表。	No
productTypes	list<string>	指定要在查詢結果中傳回的產品類型。 支援的產品類型為 Application、Durable、Game 和 UnmanagedConsumable。	Yes
validityType	字串	當設定為 All 時，將會傳回使用者的所有產品，包括過期的項目。 當設定為 Valid 時，只會傳回當下有效的產品 (也就是說，其現在有作用中狀態、開始日期 < 現在和結束日期是 >)。	No

UserIdentity 物件包含下列參數。

參數	類型	描述	必要
identityType	字串	指定字串值 b2b。	Yes
identityValue	字串	Microsoft Store 識別碼金鑰，代表您要查詢產品之使用者的身分識別。	Yes
localTicketReference	字串	傳回產品的要求識別碼。 回應主體中的傳回項目將會有相符的 localTicketReference。 建議您在 Microsoft Store 識別碼金鑰中使用與 userId 宣告相同的值。	Yes

ProductSkuId 物件包含下列參數。

參數	類型	描述	必要
productId	字串	Microsoft Store 目錄中產品的 Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。	Yes
skuId	字串	Microsoft Store 目錄中產品 SKU 的 Store ID。 SKU 的範例 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	字串	如果有多個產品集，當達到頁面限制時，就會傳回此權杖。 您可以在後續呼叫中指定此接續權杖，以擷取剩餘的產品。	No
items	CollectionItemContractV6	指定使用者的產品陣列。 如需詳細資訊，請參閱下列資料表。	No

CollectionItemContractV6 物件包含下列參數。

參數	類型	描述	必要
acquiredDate	Datetime	使用者取得項目的日期。	Yes
campaignId	字串	此項目購買時所提供的行銷活動識別碼。	No
devOfferId	字串	應用程式內購買的供應項目識別碼。	No
endDate	Datetime	項目的結束日期。	Yes
fulfillmentData	list<string>	N/A	No
inAppOfferToken	字串	開發人員指定所指派給合作夥伴中心專案中的項目產品識別碼字串。 產品標識符範例是 product123。	No
itemId	字串	識別碼可識別使用者擁有之其他專案的此集合項目。 此識別碼是每個產品專有的。	Yes
localTicketReference	字串	要求本文中先前提供的 localTicketReference 識別碼。	Yes
modifiedDate	Datetime	上次修改此項目的日期。	Yes
orderId	字串	如果存在，則會取得此項目的訂單識別碼。	No
orderLineItemId	字串	如果存在，則為取得此項目之專屬訂單的明細項目。	No
ownershipType	字串	字串 OwnedByBeneficiary。	Yes
productId	字串	Microsoft Store 目錄中產品的 Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。	是
productType	字串	下列其中一種產品類型：Application、Durable 和 UnmanagedConsumable。	Yes
purchasedCountry	字串	N/A	No
purchaser	IdentityContractV6	如果存在，這代表項目的購買者身分識別。 請參閱下方此物件的詳細資料。	No
數量	數值	項目的數量。 目前，這一律為 1。	No
skuId	字串	Microsoft Store 目錄中 SKU 的 Store ID。 SKU 的範例 Store ID 為 0010。	Yes
skuType	字串	SKU 的類型。 可能的值包括 Trial、Full 和 Rental。	Yes
startDate	Datetime	項目開始有效的日期。	Yes
狀態	字串	項目的狀態。 可能的值包括 Active、Expired、Revoked 和 Banned。	Yes
標記	list<string>	N/A	Yes
transactionId	guid	購買此項目所產生的交易識別碼。 可用於將項目回報為已履行。	Yes

IdentityContractV6 物件包含下列參數。

參數	類型	描述	必要
identityType	字串	包含值 pub。	Yes
identityValue	字串	來自指定 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"
    }
  ]
}

相關主題

• 管理服務的產品權利
• 把消耗品報告為已履行
• 免費授予產品
• 更新 Microsoft Store 識別碼金鑰
• Microsoft.StoreServices 程式庫 (GitHub)