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

[アーティクル]
06/14/2024

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

重要

コード内の使用状況を把握し、基本料金を超えた使用分についてのみ、使用状況のイベントを Microsoft に送信する必要があります。

SaaS のカスタム測定ディメンションを作成する方法の詳細については、「マーケットプレース測定サービスを使用した従量制課金」を参照してください。

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

TLS 1.2 Note を適用する

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

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

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

カレンダー日の 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 を使用します。

要求ヘッダー:

Content-type	`application/json` を使用します
`x-ms-requestid`	クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。この値を指定しないと、値が生成され、応答ヘッダーに指定されます。
`x-ms-correlationid`	クライアントでの操作に対する一意の文字列値。このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。この値を指定しないと、値が生成され、応答ヘッダーに指定されます。
`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
OK です。使用状況の生成は、さらに処理と課金を行うために、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"
}

コード: 403

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

コード: 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 を使用します。

要求ヘッダー:

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

Note

要求本文では、リソース ID の意味がカスタムメーターを発行する SaaS アプリと Azure マネージドアプリで異なります。 SaaS アプリのリソース ID は resourceID です。 Azure Application Managed Apps プランのリソース ID は resourceUri です。リソース ID の詳細については、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 アプリケーションマネージドアプリのプランの場合、resourceUri は、マネージドアプリケーションの resourceUsageId です。これを取得するためのサンプルスクリプトについては、「Azure マネージド ID トークンの使用」をご覧ください。

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
OK です。バッチ使用状況の生成は、さらに処理と課金を行うために、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 個を超える使用状況イベントが含まれていました。

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

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

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

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

クエリパラメーター:

パラメーター	推奨事項
ApiVersion	2018-08-31 を使用します。
usageStartDate	ISO8601 形式での DateTime。例: 2020-12-03T15:00、2020-12-03
UsageEndDate (省略可能)	ISO8601 形式での DateTime。既定値 = 現在の日付
offerId (省略可能)	既定値 = 使用可能なものすべて
planId (省略可能)	既定値 = 使用可能なものすべて
dimension (省略可能)	既定値 = 使用可能なものすべて
azureSubscriptionId (省略可能)	既定値 = 使用可能なものすべて
reconStatus (省略可能)	既定値 = 使用可能なものすべて

reconStatus の指定できる値:

ReconStatus	説明
送信	PC 分析によってまだ処理されていません
承認済み	PC 分析と一致しました
拒否	パイプラインで拒否されました。原因を調べるには、Microsoft サポートにお問い合わせください。
不一致	MarketplaceAPI とパートナーセンター分析の数量はどちらも 0 以外ですが、一致しません

要求ヘッダー:

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

応答

応答ペイロードの例:

承認済み*

[
  {
    "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
  }
]

提出済み

[
  {
    "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
  }
]

ミスマッチ

[
  {
    "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
  }
]

状態コード

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

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

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

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

サポートを受ける

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

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

次の方法で共有

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

TLS 1.2 Note を適用する

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

応答

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

応答

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

応答

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

サポートを受ける

フィードバック

その他のリソース

次の方法で共有

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

TLS 1.2 Note を適用する

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

応答

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

応答

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

応答

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

サポートを受ける

関連するコンテンツ

フィードバック

その他のリソース

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