製品の照会Query for products

Azure AD クライアント ID に関連付けられているアプリでユーザーが所有しているすべての製品を取得するには、Microsoft Store コレクション API の以下のメソッドを使います。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.
  • 取得対象の製品を所有するユーザーの ID を表す 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

HeaderHeader 種類Type 説明Description
AuthorizationAuthorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.
ホストHost stringstring collections.mp.microsoft.com に設定する必要があります。Must be set to the value collections.mp.microsoft.com.
Content-LengthContent-Length numbernumber 要求の本文の長さ。The length of the request body.
Content-TypeContent-Type stringstring 要求と応答の種類を指定します。Specifies the request and response type. 現時点では、サポートされている唯一の値は application/json です。Currently, the only supported value is application/json.

要求本文Request body

パラメーターParameter 種類Type 説明Description 必須Required
beneficiariesbeneficiaries useridentity & gt の一覧表示<list<UserIdentity&gt 製品のクエリを行うユーザーを表す UserIdentity オブジェクトの一覧。A list of UserIdentity objects that represent the users being queried for products. 詳細については、次の表をご覧ください。For more information, see the table below. はいYes
continuationTokencontinuationToken stringstring 製品のセットが複数ある場合、ページ制限に達すると、応答本文で継続トークンが返されます。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 numbernumber 1 つの応答で返す製品の最大数。The maximum number of products to return in one response. 既定値および最大値は 100 です。The default and maximum value is 100. いいえNo
modifiedAftermodifiedAfter DATETIMEdatetime 指定した場合、この日付以降に変更された製品だけがサービスから返されます。If specified, the service only returns products that have been modified after this date. いいえNo
parentProductIdparentProductId stringstring 指定した場合、指定されたアプリに対応するアドオンだけがサービスから返されます。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
productTypesproductTypes リスト<文字列>list<string> クエリ結果で返す製品の種類を指定します。Specifies which products types to return in the query results. サポートされている製品タイプは ApplicationDurable、および UnmanagedConsumable です。Supported product types are Application, Durable, and UnmanagedConsumable. [はい]Yes
validityTypevalidityType stringstring 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 stringstring 文字列値 b2b を指定します。Specify the string value b2b. [はい]Yes
identityValueidentityValue stringstring 照会する製品のユーザーの ID を表す Microsoft Store ID キーThe Microsoft Store ID key that represents the identity of the user for whom you want to query products. はいYes
localTicketReferencelocalTicketReference stringstring 返された製品で必要な識別子。The requested identifier for the returned products. 応答本文で返された項目には、一致する localTicketReference があります。Returned 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 の Store 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 stringstring 製品のセットが複数ある場合、ページ制限に達すると、このトークンが返されます。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
itemsitems 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 DATETIMEdatetime ユーザーが項目を取得した日付。The date on which the user acquired the item. はいYes
campaignIdcampaignId stringstring この項目の購入時に提供されたキャンペーン ID。The campaign ID that was provided at purchase time for this item. いいえNo
devOfferIddevOfferId stringstring アプリ内購入からのプラン ID。The offer ID from an in-app purchase. いいえNo
endDateendDate DATETIMEdatetime 項目の終了日。The end date of the item. はいYes
fulfillmentDatafulfillmentData stringstring なしN/A いいえNo
inAppOfferTokeninAppOfferToken stringstring パートナーセンターの項目に割り当てられている、開発者が指定した製品 ID 文字列。The developer-specified product ID string that is assigned to the item in Partner Center. たとえば、製品 ID はproduct123です。A example product ID is product123. いいえNo
itemIditemId stringstring ユーザーが所有する他の項目からこのコレクション項目を識別する 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 DATETIMEdatetime この項目が最後に更新された日付。The date this item was last modified. はいYes
orderIdorderId stringstring 存在する場合、この項目が取得された注文 ID。If present, the order ID of which this item was obtained. いいえNo
orderLineItemIdorderLineItemId stringstring 存在する場合、この項目が取得された特定の注文の行項目。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 stringstring 次のいずれかの製品の種類。アプリケーション持続性、およびUnmanagedConsumableOne of the following product types: Application, Durable, and UnmanagedConsumable. [はい]Yes
purchasedCountrypurchasedCountry stringstring なしN/A いいえNo
purchaserpurchaser IdentityContractV6IdentityContractV6 存在する場合、項目の購入者の ID を表します。If present, this represents the identity of the purchaser of the item. 下記に示すこのオブジェクトの詳細を参照してください。See the details for this object below. いいえNo
quantityquantity numbernumber 項目の数量。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 の Store ID の例は、0010 です。An example Store ID for a SKU is 0010. はいYes
skuTypeskuType stringstring SKU のタイプ。Type of the SKU. 可能な値は TrialFull、および Rental です。Possible values include Trial, Full, and Rental. はいYes
startDatestartDate DATETIMEdatetime 項目の有効期間の開始日。The date that the item starts being valid. [はい]Yes
statusstatus stringstring アイテムの状態。The status of the item. 可能な値は ActiveExpiredRevoked、および Banned です。Possible values include Active, Expired, Revoked, and Banned. [はい]Yes
tagstags stringstring なし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 pub を格納します。Contains the value pub. [はい]Yes
identityValueidentityValue stringstring 指定された 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"
    }
  ]
}