コンシューマブルな製品をフルフィルメント完了として報告するReport consumable products as fulfilled

特定のユーザーについてコンシューマブルな製品をフルフィルメント完了として報告するには、Microsoft Store コレクション API の以下のメソッドを使います。Use this method in the Microsoft Store collection API to report a consumable product as fulfilled for a given customer. ユーザーがコンシューマブルな製品を再購入するには、アプリまたはサービスが、そのユーザーについてコンシューマブルな製品をフルフィルメント完了と報告している必要があります。Before a user can repurchase a consumable product, your app or service must report the consumable product as fulfilled for that user.

このメソッドを使用してコンシューマブルな製品をフルフィルメント完了として報告するには、次の 2 つの方法があります。There are two ways you can use this method to report a consumable product as fulfilled:

  • コンシューマブルの項目 ID (製品の照会itemId パラメーターとして返されるもの)、およびユーザー指定の一意の追跡 ID を指定します。Provide the item ID of the consumable (as returned in the itemId parameter of a query for products), and a unique tracking ID that you provide. 複数の試行で同じ追跡 ID が使用される場合、項目が既に消費されている場合でも同じ結果が返されます。If the same tracking ID is used for multiple tries, the same result will be returned even if the item is already consumed. 消費要求が成功したかどうかがわからない場合は、サービスは同じ追跡 ID を使用して消費要求を再送信する必要があります。If you aren't certain if a consume request was successful, your service should resubmit consume requests with the same tracking ID. 追跡 ID は常にその消費要求に関連付けられており、無限に再送信できます。The tracking ID will always be tied to that consume request and can be resubmitted indefinitely.
  • 製品 ID (製品の照会productId パラメーターで返されるもの)、および以下の要求の本文セクションの transactionId パラメーターの記述にあるいずれかのソースから取得されるトランザクション ID を指定します。Provide the product ID (as returned in the productId parameter of a query for products) and a transaction ID that is obtained from one of the sources listed in the description for the transactionId parameter in the request body section below.

前提条件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 for whom you want to report a consumable product as fulfilled.

詳しくは、「サービスによる製品の権利の管理」をご覧ください。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/consume

要求ヘッダーRequest header

HeaderHeader 種類Type 説明Description
AuthorizationAuthorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.
HostHost 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
beneficiarybeneficiary UserIdentityUserIdentity この項目が使用されているユーザー。The user for which this item is being consumed. 詳細については、次の表を参照してください。For more information, see the following table. Yes
itemIditemId stringstring 製品の照会で返される itemId 値。The itemId value returned by a query for products. このパラメーターは trackingId と共に使用します。Use this parameter with trackingId XNo
trackingIdtrackingId guidguid 開発者により指定される一意の追跡 ID。A unique tracking ID provided by developer. このパラメーターは itemId と共に使用します。Use this parameter with itemId. XNo
productIdproductId stringstring 製品の照会で返される productId 値。The productId value returned by a query for products. このパラメーターは transactionId と共に使用します。Use this parameter with transactionId XNo
transactionIdtransactionId guidguid 次のいずれかのソースから取得されるトランザクション ID 値。A transaction ID value that is obtained from one of the following sources. このパラメーターは productId と共に使用します。Use this parameter with productId. XNo

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 report a consumable product as fulfilled. Yes
localTicketReferencelocalTicketReference stringstring 返された応答で必要な識別子。The requested identifier for the returned response. 同じ値を使用することをお勧め、 userId要求Microsoft Store の ID キー。We recommend that you use the same value as the userId claim in the Microsoft Store ID key. Yes

要求の例Request examples

次の例では、itemIdtrackingId を使用します。The following example uses itemId and trackingId.

POST https://collections.mp.microsoft.com/v6.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1…..
Host: collections.mp.microsoft.com
Content-Length: 2050
Content-Type: application/json

{
    "beneficiary": {
        "localTicketReference": "testreference",
        "identityValue": "eyJ0eXAiOi…..",
        "identityType": "b2b"
    },
    "itemId": "44c26106-4979-457b-af34-609ae97a084f",
    "trackingId": "44db79ca-e31d-49e9-8896-fa5c7f892b40"
}

次の例では、productIdtransactionId を使用します。The following example uses productId and transactionId.

POST https://collections.mp.microsoft.com/v6.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1……
Content-Length: 1880
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue" : "eyJ0eXAiOiJ…..",
        "identitytype" : "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "transactionId" : "08a14c7c-1892-49fc-9135-190ca4f10490"
}

応答Response

使用が正常に実行された場合、コンテンツは返されません。No content will be returned if the consumption was executed successfully.

応答の例Response example

HTTP/1.1 204 No Content
Content-Length: 0
MS-CorrelationId: 386f733d-bc66-4bf9-9b6f-a1ad417f97f0
MS-RequestId: e488cd0a-9fb6-4c2c-bb77-e5100d3c15b1
MS-CV: 5.1
MS-ServerId: 030011326
Date: Tue, 22 Sep 2015 20:40:55 GMT

エラー コードError codes

コードCode エラーError 内部エラー コードInner error code 説明Description
401401 権限がありませんUnauthorized AuthenticationTokenInvalidAuthenticationTokenInvalid Azure AD アクセス トークンが無効です。The Azure AD access token is invalid. 場合によっては、ServiceError の詳細に追加情報が含まれていることがあります (トークンの有効期限切れや appid 要求の欠落など)。In some cases the details of the ServiceError will contain more information, such as when the token is expired or the appid claim is missing.
401401 権限がありませんUnauthorized PartnerAadTicketRequiredPartnerAadTicketRequired Azure AD アクセス トークンが承認ヘッダーでサービスに渡されませんでした。An Azure AD access token was not passed to the service in the authorization header.
401401 権限がありませんUnauthorized InconsistentClientIdInconsistentClientId 要求本文の Microsoft Store ID の clientId 要求と承認ヘッダーの Azure AD アクセス トークンの appid 要求が一致しません。The clientId claim in the Microsoft Store ID key in the request body and the appid claim in the Azure AD access token in the authorization header do not match.