次の方法で共有

purchase.mp.microsoft.com/v8.0/purchases/grant

  • [アーティクル]

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

現時点では、無料の製品のみを付与することができます。 サービスが無料でない製品を付与しようとすると、エラーが返されます。

前提条件

注意

現時点では、購入 API では XSTS トークン認証をサポートしていません。

この API を使用するには、以下が必要になります。

  • 対象ユーザーの URI 値 https://onestore.microsoft.com を持つ Microsoft Entra ID アクセス トークン
  • 付与する無料製品のユーザーの ID を表すユーザー購入 ID キー

詳細については、「サーバー間認証にユーザー Store ID を要求する」を参照してください。

さらに、サービスに表示できるようにする製品には、パートナー センターでの追加の構成が必要です。

製品を適切に構成する方法については、「ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成」を参照してください。

注意

製品の構成がまだ行われておらず、パートナー センター経由で発行された場合、購入サービスの呼び出しは成功しますが、応答に結果は入りません。

要求

要求の構文

メソッド 要求 URI
POST https://purchase.mp.microsoft.com/v7.0/purchases/grant

要求ヘッダー

ヘッダー 型 説明
Authorization string 必須。 Bearer < トークン> という形式の Microsoft Entra ID サービス アクセス トークン。
Host string 値 purchase.mp.microsoft.com を設定する必要があります。
Content-Length number 要求本文の長さ。
Content-Type string 要求と応答の種類を指定します。 現在唯一サポートされている値は application/json です。

リクエストの本文

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

要求の例

POST https://purchase.mp.microsoft.com/v7.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",
    "sbx" : "XDKS.1"
}

応答

応答の本文

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

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

パラメーター 型 説明 必須
client string 注文を作成したクライアント ID。 いいえ

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

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

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

パラメーター 型 説明 必須
identityType string 値 "pub" が含まれます。 はい
identityValue string 指定されたユーザー 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: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 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 Microsoft Entra ID アクセス トークンが無効です。 場合によっては、ServiceError の詳細に追加情報が含まれることがあります (トークンの有効期限切れや appid 要求の欠落など)。
401 未承認 PartnerAadTicketRequired Microsoft Entra ID アクセス トークンが承認ヘッダー内のサービスに渡されませんでした。
401 未承認 InconsistentClientId 要求本文の User Store ID キーの clientId 要求と、承認ヘッダーの Microsoft Entra ID アクセス トークン内の appid 要求が一致しません。
400 BadRequest InvalidParameter 詳細情報に、要求の本文と無効な値を含むフィールドに関する情報が含まれます。

サービスから製品を管理する

サービスからサービスへの認証にユーザー Store ID を要求する

Microsoft Store ID キーの更新