無料の製品の付与Grant free products

無料のアプリまたはアドオン (アプリ内製品または IAP とも呼ばれます) を特定のユーザーに付与するには、Microsoft Store 購入 API の以下のメソッドを使います。Use this method in the Microsoft Store purchase API to grant a free app or add-on (also known as in-app product or IAP) to a given user.

現時点では、無料の製品のみを付与することができます。Currently, you can only grant free products. サービスがこのメソッドを使用して無料でない製品を付与しようとすると、このメソッドはエラーを返します。If your service attempts to use this method to grant a product that is not free, this method will return an error.

前提条件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 grant a free product.

詳しくは、「サービスによる製品の権利の管理」をご覧ください。For more information, see Manage product entitlements from a service.

要求Request

要求の構文Request syntax

メソッドMethod 要求 URIRequest URI
POSTPOST https://purchase.mp.microsoft.com/v6.0/purchases/grant

要求ヘッダーRequest header

HeaderHeader 種類Type 説明Description
AuthorizationAuthorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.
HostHost stringstring purchase.mp.microsoft.com に設定する必要があります。Must be set to the value purchase.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
availabilityIdavailabilityId stringstring Microsoft Store カタログから付与される製品の可用性 ID。The availability ID of the product to be granted from the Microsoft Store catalog. Yes
b2bKeyb2bKey stringstring 製品を付与するユーザーの ID を表す Microsoft Store ID キーThe Microsoft Store ID key that represents the identity of the user for whom you want to grant a product. Yes
devOfferIddevOfferId stringstring 購入後にコレクション項目に表示される開発者指定のプラン ID。A developer-specified offer ID that will appear in the Collection item after purchase.
言語language stringstring ユーザーの言語。The language of the user. Yes
marketmarket stringstring ユーザーの市場。The market of the user. Yes
orderIdorderId guidguid 注文に対して生成された GUID。A GUID generated for the order. この値はそのユーザーに関して一意ですが、すべての注文にわたって一意である必要はありません。This value be unique for the user, but it is not required to be unique across all orders. 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
quantityquantity intint 購入する数量。The quantity to purchase. 現時点では、サポートされている唯一の値は 1 です。Currently, the only supported value is 1. 指定されていない場合は、既定値は 1 です。If not specified, the default is 1. XNo
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

要求の例Request example

POST https://purchase.mp.microsoft.com/v6.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK……
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK……",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
}

応答Response

応答本文Response body

パラメーターParameter 種類Type 説明Description 必須Required
clientContextclientContext ClientContextV6ClientContextV6 この注文に対するクライアントのコンテキスト情報。Client contextual information for this order. これは、Azure AD トークンの clientID 値に割り当てられます。This will be assigned to the clientID value from the Azure AD token. Yes
createdtimecreatedtime datetimeoffsetdatetimeoffset 注文が作成された時刻。The time the order was created. Yes
currencyCodecurrencyCode stringstring totalAmounttotalTaxAmount の通貨コード。Currency code for totalAmount and totalTaxAmount. 無料の項目の場合は該当なし。N/A for free items. Yes
friendlyNamefriendlyName stringstring 注文のフレンドリ名。The friendly name for the order. Microsoft Store 購入 API を使用した注文の場合は該当なし。N/A for orders made using the Microsoft Store purchase API. Yes
isPIRequiredisPIRequired booleanboolean 注文の一部として支払い方法 (PI) が必要かどうかを示します。Indicates whether a payment instrument (PI) is required as part of the purchase order. Yes
言語language stringstring 注文の言語 ID (たとえば “en”)。The language ID for the order (for example, “en”). Yes
marketmarket stringstring 注文の市場 ID (たとえば “US”)。The market ID for the order (for example, “US”). Yes
orderIdorderId stringstring 特定のユーザーの注文を識別する ID。An ID that identifies the order for a particular user. Yes
orderLineItemsorderLineItems list<OrderLineItemV6>list<OrderLineItemV6> 注文の行項目の一覧。The list of line items for the order. 通常は、注文あたり 1 つの行項目があります。Typically there is 1 line item per order. Yes
orderStateorderState stringstring 注文の状態。The state of the order. 有効な状態は、EditingCheckingOutPendingPurchasedRefundedChargedBack、および Cancelled です。The valid states are Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack, and Cancelled. Yes
orderValidityEndTimeorderValidityEndTime stringstring 注文を送信する前の、注文の価格が有効である最後の時刻。The last time the order pricing is valid before it is submitted. 無料アプリの場合は該当なし。N/A for free apps. Yes
orderValidityStartTimeorderValidityStartTime stringstring 注文を送信する前の、注文の価格が有効である最初の時刻。The first time the order pricing is valid before it is submitted. 無料アプリの場合は該当なし。N/A for free apps. Yes
purchaserpurchaser IdentityV6IdentityV6 購入者の ID を表すオブジェクト。An object that describes the identity of the purchaser. Yes
totalAmounttotalAmount decimaldecimal 注文のすべての項目の税込みの合計購入金額。The total purchase amount of all items in the order including tax. Yes
totalAmountBeforeTaxtotalAmountBeforeTax decimaldecimal 注文のすべての項目の税抜きの合計購入金額。Total purchase amount of all items in the order before tax. Yes
totalChargedToCsvTopOffPItotalChargedToCsvTopOffPI decimaldecimal 個別の支払い方法とストアド バリュー (CSV) を使っている場合に、CSV に請求する金額。If using a separate payment instrument and stored value (CSV), the amount charged to CSV. Yes
totalTaxAmounttotalTaxAmount decimaldecimal すべての行項目に対する税の合計金額。The total amount of tax for all line items. Yes

ClientContext オブジェクトには以下のパラメーターが含まれています。The ClientContext object contains the following parameters.

パラメーターParameter 種類Type 説明Description 必須Required
clientclient stringstring 注文を作成したクライアント ID。The client ID that created the order. いいえNo

OrderLineItemV6 オブジェクトには以下のパラメーターが含まれています。The OrderLineItemV6 object contains the following parameters.

パラメーターParameter 種類Type 説明Description 必須Required
agentagent IdentityV6IdentityV6 行項目を最後に編集したエージェント。The agent that last edited the line item. このオブジェクトについて詳しくは、次の表をご覧ください。For more information about this object, see the table below. XNo
availabilityIdavailabilityId stringstring Microsoft Store カタログから購入される製品の可用性 ID。The availability ID of the product to be purchased from the Microsoft Store catalog. Yes
beneficiarybeneficiary IdentityV6IdentityV6 注文の受益者の ID。The identity of the beneficiary of the order. XNo
billingStatebillingState stringstring 注文の請求の状態。The billing state of the order. 完了すると、これは Charged に設定されます。This is set to Charged when completed. XNo
campaignIdcampaignId stringstring この注文のキャンペーン ID。The campaign ID for this order. XNo
currencyCodecurrencyCode stringstring 価格の詳細に使用される通貨コード。The currency code used for price details. Yes
説明description stringstring 行項目のローカライズされた説明。A localized description of the line item. Yes
devofferIddevofferId stringstring 特定の注文のプラン ID (該当する場合)。The offer ID for the particular order, if present. いいえNo
fulfillmentDatefulfillmentDate datetimeoffsetdatetimeoffset フルフィルメントが発生した日付。The date the fulfillment occurred. XNo
fulfillmentStatefulfillmentState stringstring この項目のフルフィルメントの状態。The state of the fulfillment of this item. 完了すると、これは Fulfilled に設定されます。This is set to Fulfilled when completed. いいえNo
isPIRequiredisPIRequired booleanboolean この行項目について支払い方法が必要であるかどうかを示します。Indicates whether a payment instrument is required for this line item. Yes
isTaxIncludedisTaxIncluded booleanboolean 項目の価格の詳細に税が含まれているかどうかを示します。Indicated whether tax is included in the pricing details of the item. Yes
legacyBillingOrderIdlegacyBillingOrderId stringstring 従来の課金 ID。The legacy billing ID. XNo
lineItemIdlineItemId stringstring この注文の項目の行項目 ID。The line item ID for the item in this order. Yes
listPricelistPrice decimaldecimal この注文の項目の定価。The list price of the item in this order. Yes
productIdproductId stringstring Microsoft Store カタログでの行項目を表す製品Store IDThe Store ID for the product that represents the line item in the Microsoft Store catalog. 製品のストア ID の例は、9NBLGGH42CFD です。An example Store ID for a product is 9NBLGGH42CFD. Yes
productTypeproductType stringstring 製品の種類。The type of the product. サポートされる値は、DurableApplication、および UnmanagedConsumable です。The supported values are Durable, Application, and UnmanagedConsumable. Yes
quantityquantity intint 注文された項目の数量。The quantity of the item ordered. Yes
retailPriceretailPrice decimaldecimal 注文された項目の小売価格。The retail price of the item ordered. Yes
revenueRecognitionStaterevenueRecognitionState stringstring 収益認識の状態。The revenue recognition state. Yes
skuIdskuId stringstring Microsoft Store カタログ内の品目の SKUStore IDThe Store ID for the SKU of the line item in the Microsoft Store catalog. SKU の Store ID の例は、0010 です。An example Store ID for a SKU is 0010. Yes
taxAmounttaxAmount decimaldecimal 行項目の税額。The tax amount for the line item. Yes
taxTypetaxType stringstring 適用される税金の種類。The tax type for the applicable taxes. Yes
タイトルTitle stringstring 行項目のローカライズされたタイトル。The localized title of the line item. Yes
totalAmounttotalAmount decimaldecimal 行項目の税込みの合計購入金額。The total purchase amount of the line item including tax. Yes

IdentityV6 オブジェクトには以下のパラメーターが含まれています。The IdentityV6 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

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

エラー コード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.
400400 BadRequestBadRequest InvalidParameterInvalidParameter 詳細情報に、要求の本文と無効な値を含むフィールドに関する情報が含まれます。The details contain information regarding the request body and which fields have an invalid value.