無料の製品の付与

[アーティクル]
07/05/2024

無料のアプリまたはアドオン (アプリ内製品または IAP とも呼ばれます) を特定のユーザーに付与するには、Microsoft Store 購入 API の以下のメソッドを使います。

現時点では、無料の製品のみを付与することができます。サービスがこのメソッドを使用して無料でない製品を付与しようとすると、このメソッドはエラーを返します。

前提条件

このメソッドを使用するための要件:

対象ユーザー URI の値が https://onestore.microsoft.com の Azure AD アクセストークン。
無料製品を付与するユーザーの ID を表す Microsoft Store ID キー。

詳しくは、「サービスによる製品の権利の管理」をご覧ください。

要求

要求の構文

認証方法	要求 URI
POST	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

要求ヘッダー

Header	型	説明
承認	string	必須。 Bearer<トークン> という形式の Azure AD アクセストークン。
Host	string	値 purchase.mp.microsoft.com に設定する必要があります。
Content-Length	number	要求本文の長さです。
Content-Type	string	要求と応答の種類を指定します。現時点では、サポートされている唯一の値は application/json です。

要求本文

パラメーター	型	内容	必須
availabilityId	string	Microsoft Store カタログから付与される製品の可用性 ID。	はい
b2bKey	string	製品を付与するユーザーの ID を表す Microsoft Store ID キー。	はい
devOfferId	string	購入後にコレクション項目に表示される開発者指定のプラン ID。
language	string	ユーザーの言語。	はい
market	string	ユーザーの市場。	はい
orderId	guid	注文に対して生成された GUID。この値はそのユーザーに関して一意ですが、すべての注文にわたって一意である必要はありません。	はい
productId	string	Microsoft Store カタログ内の製品の Store ID。製品のストア ID の例は、9NBLGGH42CFD です。	はい
数量	int	購入する数量。現時点では、サポートされている唯一の値は 1 です。指定しない場合は、1 が既定値です。	No
skuId	string	Microsoft Store カタログ内の製品の SKU の Store ID。 SKU の Store ID の例は、0010 です。	はい

要求の例

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",
}

[応答]

応答本文

パラメーター	型	内容	必須
clientContext	ClientContextV6	この注文に対するクライアントのコンテキスト情報。これは、Azure AD トークンの clientID 値に割り当てられます。	はい
createdtime	datetimeoffset	注文が作成された時刻。	はい
currencyCode	string	totalAmount と totalTaxAmount の通貨コード。無料の項目の場合は該当なし。	はい
friendlyName	string	注文のフレンドリ名。 Microsoft Store 購入 API を使用した注文の場合は該当なし。	はい
isPIRequired	boolean	注文の一部として支払い方法 (PI) が必要かどうかを示します。	はい
language	string	注文の言語 ID (たとえば “en”)。	はい
market	string	注文の市場 ID (たとえば “US”)。	はい
orderId	string	特定のユーザーの注文を識別する ID。	はい
orderLineItems	list<OrderLineItemV6>	注文の行項目の一覧。通常は、注文あたり 1 つの行項目があります。	はい
orderState	string	注文の状態。有効な状態は、Editing、CheckingOut、Pending、Purchased、Refunded、ChargedBack、および Cancelled です。	はい
orderValidityEndTime	string	注文を送信する前の、注文の価格が有効である最後の時刻。無料アプリの場合は該当なし。	はい
orderValidityStartTime	string	注文を送信する前の、注文の価格が有効である最初の時刻。無料アプリの場合は該当なし。	はい
purchaser	IdentityV6	購入者の ID を表すオブジェクト。	はい
totalAmount	decimal	注文のすべての項目の税込みの合計購入金額。	はい
totalAmountBeforeTax	decimal	注文のすべての項目の税抜きの合計購入金額。	はい
totalChargedToCsvTopOffPI	decimal	個別の支払い方法とストアドバリュー (CSV) を使っている場合に、CSV に請求する金額。	はい
totalTaxAmount	decimal	すべての行項目に対する税の合計金額。	はい

ClientContext オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	内容	必須
クライアント	string	注文を作成したクライアント ID。	No

OrderLineItemV6 オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	内容	必須
エージェント	IdentityV6	行項目を最後に編集したエージェント。このオブジェクトについて詳しくは、次の表をご覧ください。	No
availabilityId	string	Microsoft Store カタログから購入される製品の可用性 ID。	はい
beneficiary	IdentityV6	注文の受益者の ID。	No
billingState	string	注文の請求の状態。完了すると、これは Charged に設定されます。	No
campaignId	string	この注文のキャンペーン ID。	No
currencyCode	string	価格の詳細に使用される通貨コード。	はい
説明	string	行項目のローカライズされた説明。	はい
devofferId	string	特定の注文のプラン ID (該当する場合)。	No
fulfillmentDate	datetimeoffset	フルフィルメントが発生した日付。	No
fulfillmentState	string	この項目のフルフィルメントの状態。完了すると、これは Fulfilled に設定されます。	No
isPIRequired	boolean	この行項目について支払い方法が必要であるかどうかを示します。	はい
isTaxIncluded	boolean	項目の価格の詳細に税が含まれているかどうかを示します。	はい
legacyBillingOrderId	string	従来の課金 ID。	No
lineItemId	string	この注文の項目の行項目 ID。	はい
listPrice	decimal	この注文の項目の定価。	はい
productId	string	Microsoft Store カタログでの行項目を表す製品の Store ID。製品のストア ID の例は、9NBLGGH42CFD です。	はい
productType	string	製品の種類。サポートされる値は、Durable、Application、および UnmanagedConsumable です。	はい
数量	int	注文された項目の数量。	はい
retailPrice	decimal	注文された項目の小売価格。	はい
revenueRecognitionState	string	収益認識の状態。	はい
skuId	string	Microsoft Store カタログ内の品目の SKU の Store ID。 SKU の Store ID の例は、0010 です。	はい
taxAmount	decimal	行項目の税額。	はい
taxType	string	適用される税金の種類。	はい
タイトル	string	行項目のローカライズされたタイトル。	はい
totalAmount	decimal	行項目の税込みの合計購入金額。	はい

IdentityV6 オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	内容	必須
identityType	string	値 "pub" を格納します。	はい
identityValue	string	指定された Microsoft Store ID キーの publisherUserId の文字列値。	はい

応答の例

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
}

エラーコード

コード	エラー	内部エラーコード	説明
401	権限がありません	AuthenticationTokenInvalid	Azure AD アクセストークンが無効です。場合によっては、ServiceError の詳細に追加情報が含まれていることがあります (トークンの有効期限切れや appid 要求の欠落など)。
401	権限がありません	PartnerAadTicketRequired	Azure AD アクセストークンが承認ヘッダーでサービスに渡されませんでした。
401	権限がありません	InconsistentClientId	要求本文の Microsoft Store ID の clientId 要求と承認ヘッダーの Azure AD アクセストークンの appid 要求が一致しません。
400	BadRequest	InvalidParameter	詳細情報に、要求の本文と無効な値を含むフィールドに関する情報が含まれます。

次の方法で共有

無料の製品の付与

前提条件

要求

要求の構文

要求ヘッダー

要求本文

要求の例

[応答]

応答本文

応答の例

エラーコード

フィードバック

その他のリソース

次の方法で共有

無料の製品の付与

前提条件

要求

要求の構文

要求ヘッダー

要求本文

要求の例

[応答]

応答本文

応答の例

エラー コード

関連トピック

フィードバック

その他のリソース

エラーコード