マーケットプレースの従量制課金 API

[アーティクル]
02/06/2025

従量制課金 API は、パブリッシャーがパートナーセンターで発行するオファーのカスタム測定ディメンションを作成するときに使用する必要があります。従量制課金 API との統合は、使用状況イベントを生成するためのカスタムディメンションを持つ 1 つ以上のプランを持つ購入済みオファーに必要です。

重要

コード内の使用状況を追跡し、基本料金を超える使用量に対してのみ使用状況イベントを Microsoft に送信する必要があります。

SaaS のカスタム測定ディメンションの作成の詳細については、SaaS 従量制課金を参照してください。

マネージドアプリプランを使用して Azure アプリケーションオファーのカスタム測定ディメンションを作成する方法の詳細については、「Azure アプリケーションオファーのセットアップの詳細構成する」を参照してください。

TLS 1.2 の適用に関する注意

TLS バージョン 1.2 バージョンは、HTTPS 通信の最小バージョンとして適用されます。コードでこの TLS バージョンを使用していることを確認します。 TLS バージョン 1.0 と 1.1 は非推奨となり、接続の試行は拒否されます。

従量制課金の単一使用イベント

特定の顧客が購入したプランのアクティブなリソース (サブスクライブ済み) に対して使用状況イベントを生成するには、パブリッシャーが使用状況イベント API を呼び出す必要があります。使用状況イベントは、オファーの発行時に発行元によって定義されたプランのカスタムディメンションごとに個別に生成されます。

リソースとディメンションごとにカレンダー日の 1 時間ごとに生成できる使用状況イベントは 1 つだけです。 1 時間に複数のユニットが消費される場合は、1 時間に消費されたすべてのユニットを蓄積し、1 つのイベントで出力します。使用状況イベントは、過去 24 時間のみ生成できます。使用イベントを 8:00 から 8:59:59 (および受け入れ可能) の間にいつでも生成し、同じ日の 8:00 から 8:59:59 の間に追加のイベントを送信すると、重複として拒否されます。

POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>

クエリパラメーター:

パラメーター	勧告
`ApiVersion`	2018-08-31 を使用します。

要求ヘッダー:

コンテンツタイプ	`application/json` を使用する
`x-ms-requestid`	クライアントからの要求を追跡するための一意の文字列値 (できれば GUID)。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
`x-ms-correlationid`	クライアントでの操作の一意の文字列値。このパラメーターは、クライアント操作のすべてのイベントをサーバー側のイベントと関連付けます。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
`authorization`	この API 呼び出しを行っている ISV を識別する一意のアクセストークン。トークン値がパブリッシャーによって取得される場合、フォーマットは `"Bearer <access_token>"` になります。その理由は次の説明に基づいています。「HTTP POST を使用したトークンの取得」での SaaS。認証戦略のマネージドアプリケーション。

リクエスト本文の例:

{
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. 
  "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
  "planId": "plan1", // id of the plan purchased for the offer
}

Azure Application Managed Apps プランの場合、resourceId はマネージドアプリ resource group Idです。それをフェッチするためのスクリプトの例は、「Azure マネージド ID トークンの使用」で見つけることができます。

SaaS オファーの場合、resourceId は SaaS サブスクリプション ID です。 SaaS サブスクリプションの詳細については、サブスクリプションの一覧参照してください。

応答

コード: 200
わかりました。使用量の排出量が受け入れられ、Microsoft 側で記録され、さらに処理と課金が行われました。

応答ペイロードの例:

{
  "usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
  "status": "Accepted" // this is the only value in case of single usage event
  "messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
  "quantity": 5.0, // amount of emitted units as recorded by Microsoft
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
  "planId": "plan1", // id of the plan purchased for the offer
}

コード: 400
要求が正しくありません。

指定された要求データが見つからないか無効です。
effectiveStartTime は過去 24 時間を超えています。イベントの有効期限が切れています。
SaaS サブスクリプションがサブスクライブ済みの状態ではありません。

応答ペイロードの例:

{
  "message": "One or more errors have occurred.",
  "target": "usageEventRequest",
  "details": [
    {
      "message": "The resourceId is required.",
      "target": "ResourceId",
      "code": "BadArgument"
    }
  ],
  "code": "BadArgument"
}

コード: 401 未承認。承認トークンが無効であるか、有効期限が切れています。要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。

コード: 403 禁止。承認トークンが無効であるか、指定されていないか、十分なアクセス許可が提供されていません。有効な承認トークンを必ず指定してください。

コード: 409
葛藤。指定されたリソース ID、有効な使用日、および時間について、使用状況イベントが既に正常に報告されています。

応答ペイロードの例:

{
  "additionalInfo": {
    "acceptedMessage": {
      "usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
      "status": "Duplicate",
      "messageTime": "2020-01-12T13:19:35.3458658Z",
      "resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
      "quantity": 1.0,
      "dimension": "dim1",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "plan1"
    }
  },
  "message": "This usage event already exist.",
  "code": "Conflict"
}

従量制課金のバッチ使用イベント

バッチ使用状況イベント API を使用すると、複数の購入済みリソースの使用状況イベントを一度に出力できます。また、カレンダー時間が異なる限り、同じリソースに対して複数の使用状況イベントを出力することもできます。 1 つのバッチ内のイベントの最大数は 25 です。

POST:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>

クエリパラメーター:

パラメーター	勧告
`ApiVersion`	2018-08-31 を使用します。

要求ヘッダー:

コンテンツタイプ	`application/json` を使用する
`x-ms-requestid`	クライアントからの要求を追跡するための一意の文字列値 (できれば GUID)。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
`x-ms-correlationid`	クライアントでの操作の一意の文字列値。このパラメーターは、クライアント操作のすべてのイベントをサーバー側のイベントと関連付けます。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
`authorization`	この API 呼び出しを行っている ISV を識別する一意のアクセストークン。形式は、パブリッシャーがトークン値を取得するときに説明された通りに`Bearer <access_token>`です。 SaaS ので HTTP POSTを使用してトークンを取得します。認証戦略のマネージドアプリケーション。

手記

要求本文では、リソース識別子は、SaaS アプリとカスタムメーターを出力する Azure マネージドアプリの意味が異なります。 SaaS アプリのリソース識別子が resourceID。 Azure Application Managed Apps プランのリソース識別子が resourceUri。リソース識別子の詳細については、「Azure Marketplace 従量制課金 - 使用状況イベントを送信するときに正しい ID を選択するを参照してください。

SaaS アプリの要求本文の例:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // next event
      "resourceId": "<guid2>", 
      "quantity": 39.0, 
      "dimension": "email", 
      "effectiveStartTime": "2018-11-01T23:33:10
      "planId": "gold", // id of the plan purchased for the offer
    }
  ]
}

Azure Application Managed Apps プランの場合、resourceUri はマネージドアプリケーション resourceUsageIdです。例のスクリプトは、Azure マネージドアイデンティティトークンを使用してで見つけることができます。

Azure アプリケーションマネージドアプリの要求本文の例:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    }
  ]
}

応答

コード: 200
わかりました。バッチ使用量の排出量が受け入れられ、Microsoft 側で記録され、さらに処理と課金が行われました。応答リストは、バッチ内の個々のイベントの状態と共に返されます。バッチイベントの一部として送信された個々の使用状況イベントの応答を理解するには、応答ペイロードを反復処理する必要があります。

応答ペイロードの例:

{
  "count": 2, // number of records in the response
  "result": [
    { // first response
      "usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
      "status": "Accepted" // see list of possible statuses below,
      "messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
      "resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
      "quantity": 5.0, // amount of emitted units as recorded by Microsoft 
      "dimension": "dim1", // custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // second response
      "status": "Duplicate",
      "messageTime": "0001-01-01T00:00:00",
      "error": {
        "additionalInfo": {
          "acceptedMessage": {
            "usageEventId": "<guid>",
            "status": "Duplicate",
            "messageTime": "2020-01-12T13:19:35.3458658Z",
            "resourceId": "<guid2>",
            "quantity": 1.0,
            "dimension": "email",
            "effectiveStartTime": "2020-01-12T11:03:28.14Z",
            "planId": "gold"
          }
        },
        "message": "This usage event already exist.",
        "code": "Conflict"
      },
      "resourceId": "<guid2>",
      "quantity": 1.0,
      "dimension": "email",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "gold"
    }
  ]
}

BatchUsageEvent API 応答で参照される状態コードの説明:

状態コード	説明
`Accepted`	承認された。
`Expired`	使用期限切れ。
`Duplicate`	重複する使用が指定されました。
`Error`	エラーコード。
`ResourceNotFound`	指定された使用状況リソースが無効です。
`ResourceNotAuthorized`	このリソースの使用状況を提供する権限がありません。
`ResourceNotActive`	リソースが中断されているか、アクティブ化されませんでした。
`InvalidDimension`	使用量が渡されるディメンションは、このオファー/プランでは無効です。
`InvalidQuantity`	渡される数量は 0 以下です。
`BadArgument`	入力が欠落しているか、形式が正しくありません。

コード: 400
要求が正しくありません。バッチには、25 を超える使用状況イベントが含まれていました。

従量制課金での使用イベントの取得

使用状況イベント API を呼び出して、使用状況イベントの一覧を取得できます。 ISV は、この API を使用して、特定の構成可能な期間に投稿された使用状況イベントと、API を呼び出した時点でのこれらのイベントの状態を確認できます。

GET: https://marketplaceapi.microsoft.com/api/usageEvents

クエリパラメーター:

パラメーター	勧告
ApiVersion	2018-08-31を使用期限とします。
使用開始日	ISO8601形式の DateTime。たとえば、2020-12-03T15:00 や 2020-12-03 などです。
使用終了日 (任意)	ISO8601形式の DateTime。既定値 = 現在の日付
offerId（任意）	既定値 = 使用可能なすべての値
planId (省略可能)	既定値 = 使用可能なすべての値
dimension (省略可能)	既定値 = 使用可能なすべての値
azureSubscriptionId (省略可能)	デフォルト = すべて利用可能
reconStatus (省略可能)	既定値 = 使用可能なすべての値

reconStatusの使用可能な値:

ReconStatus	説明
Submitted	PC Analytics でまだ処理されていません
Accepted	PC Analytics と一致
拒否	パイプラインで拒否されました。原因を調査するには、Microsoft サポートにお問い合わせください。
ミスマッチ	MarketplaceAPI とパートナーセンター分析の数量はどちらも 0 以外ですが、一致しません

要求ヘッダー:

コンテンツタイプ	application/json を使用する
x-ms-requestid	クライアントからの要求を追跡するための一意の文字列値 (できれば GUID)。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
x-ms-correlationid	クライアントでの操作の一意の文字列値。このパラメーターは、クライアント操作のすべてのイベントをサーバー側のイベントと関連付けます。この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。
認可	この API 呼び出しを行っている ISV を識別する一意のアクセストークン。トークン値がパブリッシャーによって取得されるとき、形式は `Bearer <access_token>` です。詳細については、以下を参照してください。 SaaS で、HTTP POST を使用してトークンを取得する認証戦略でのマネージドアプリケーション

応答

応答ペイロードの例:

承認済み*

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
   "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Accepted",
    "submittedQuantity": 17.0,
    "processedQuantity": 17.0,
    "submittedCount": 17
  }
]

Submitted

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Submitted",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

Mismatch

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Mismatch",
    "submittedQuantity": 17.0,
    "processedQuantity": 16.0,
    "submittedCount": 17
  }
]

拒否された

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Rejected",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

状態コード

開発とテストのベストプラクティス

カスタム測定の排出量をテストするには、測定 API との統合を実装し、発行済みの SaaS オファーのプランを作成し、1 ユニットあたりの価格をゼロにしてカスタムディメンションを定義します。また、このオファーをプレビューとして発行すると、制限付きユーザーのみが統合にアクセスしてテストできるようになります。

既存のライブオファーのプライベートプランを使用して、テスト中にこのプランへのアクセスを制限対象ユーザーに制限することもできます。

サポートを受ける

パートナーセンターのコマーシャルマーケットプレースプログラムのサポートの指示に従って、発行元のサポートオプションを理解し、Microsoft でサポートチケットを開きます。

測定サービス API の詳細については、「Marketplace 測定サービス API の FAQ 」を参照してください。

次の方法で共有

マーケットプレースの従量制課金 API

TLS 1.2 の適用に関する注意

従量制課金の単一使用イベント

応答

従量制課金のバッチ使用イベント

応答

従量制課金での使用イベントの取得

応答

開発とテストのベストプラクティス

サポートを受ける

フィードバック

その他のリソース

次の方法で共有

マーケットプレースの従量制課金 API

TLS 1.2 の適用に関する注意

従量制課金の単一使用イベント

応答

従量制課金のバッチ使用イベント

応答

従量制課金での使用イベントの取得

応答

開発とテストのベスト プラクティス

サポートを受ける

関連コンテンツ

フィードバック

その他のリソース

開発とテストのベストプラクティス