Marketplace 計量計費 API

發行項
03/11/2025

當發行者為欲在合作夥伴中心發佈的一項產品方案建立自定義計量維度時，應該使用計量計費 API 接口。任何已購買的方案中，如果有一個或多個計劃包含自定義維度且需要生成使用量事件，則必須與計量計費 API 整合。

重要

您必須追蹤程序代碼中的使用量，並只針對高於基本費用的使用量，將使用量事件傳送至Microsoft。

如需為 SaaS 建立自訂計量維度的詳細資訊，請參閱 SaaS 計量計費。

如需使用受控應用程式方案為 Azure 應用程式供應專案建立自定義計量維度的詳細資訊，請參閱設定 Azure 應用程式供應專案設定詳細資料。

TLS 1.2 強制執行說明

TLS 1.2 版會強制執行為 HTTPS 通訊的最低版本。請確定您在程式代碼中使用這個 TLS 版本。 TLS 1.0 和 1.1 版已被取代，且將會拒絕連線嘗試。

計量計費單次使用事件

發行者應該呼叫使用事件 API，針對特定客戶購買的方案內的活躍資源（已訂閱）發出使用事件。發行者在發佈供應方案時，針對每個方案定義的自訂維度，會分別發送使用事件。

每個資源和維度在一個日曆日的每個小時內最多只能發出一個使用事件。如果在一小時內取用一個以上的單位，則累積一小時內取用的所有單位，然後在單一事件中發出。僅能發出過去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」。如果未提供此值，則會在響應標頭中產生和提供一個值。
`x-ms-correlationid`	用於客戶端操作的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生和提供一個值。
`authorization`	識別進行此 API 呼叫之 ISV 的唯一存取令牌。當發行者按照說明擷取令牌值時，其格式為`"Bearer <access_token>"`。中的 SaaS 使用 HTTP POST取得令牌。驗證策略中的受控應用程式。

要求本文範例：

{
  "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 應用程式受控應用程式方案，resourceId 是受控應用程式 resource group Id。在中可以找到一個範例腳本，用於利用 Azure 受控識別令牌來擷取它。

對於 SaaS 供應專案，resourceId 是 SaaS 訂用帳戶標識碼。如需 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 未授權。授權令牌無效或已過期。該請求嘗試存取一項 SaaS 訂閱，此訂閱所屬的方案發佈時所用的 Microsoft Entra 應用程式 ID 與用來建立驗證權杖的 ID 不同。

代碼：403 禁止。授權令牌無效，或者未提供，或者提供時許可權不足。請務必提供有效的授權令牌。

程序代碼：409
衝突。已針對指定的資源標識碼、有效的使用日期與小時成功報告使用量事件。

響應負載範例：

{
  "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 可讓您一次發出多個已購買資源的使用量事件。它也可讓您發出相同資源的數個使用量事件，只要它們適用於不同的行事歷時數。單一批次中事件的最大數目為25。

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

查詢參數：

參數	建議
`ApiVersion`	於 2018-08-31 使用。

請求標頭：

內容類型	使用 `application/json`
`x-ms-requestid`	用於追蹤客戶端請求的唯一字串值，最好是「GUID」。如果未提供此值，則會產生一個值，並在響應標頭中提供。
`x-ms-correlationid`	用於客戶端操作的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會產生一個值，並在響應標頭中提供。
`authorization`	識別進行此 API 呼叫之 ISV 的唯一存取令牌。當發行者擷取令牌值時，其格式如上所述為 `Bearer <access_token>`。中的 SaaS 使用 HTTP POST取得令牌。驗證策略中的受控應用程式。

注意

在要求主體中，資源標識碼對於 SaaS 應用程式和發出自定義計量的 Azure 受控應用程式有不同的意義。 SaaS 應用程式的資源識別碼 resourceID。 Azure 應用程式受控應用程式計畫的資源識別碼為 resourceUri。如需資源識別碼的詳細資訊，請參閱 Azure Marketplace 計量計費 - 在提交使用量事件時挑選正確的標識碼。

對於 SaaS 供應專案，resourceId 是 SaaS 訂用帳戶標識碼。如需 SaaS 訂用帳戶的詳細資訊，請參閱清單訂用帳戶。

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 受控識別令牌來擷取它。

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個使用事件。

代碼：403 禁止。授權令牌無效，或者未提供，或者提供時許可權不足。請務必提供有效的授權令牌。

計量計費擷取使用事件記錄

您可以呼叫使用量事件 API 來取得使用事件清單。 ISV 可以使用此 API 查看在特定可設定期間內張貼的使用事件，以及這些事件在呼叫 API 時的狀態。

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

查詢參數：

參數	建議
ApiVersion	請於 2018-08-31 使用。
使用開始日期	ISO8601格式的 DateTime。例如，2020-12-03T15：00 或 2020-12-03
UsageEndDate （選擇性）	ISO8601格式的 DateTime。預設值 = 目前日期
offerId （選擇性）	預設值 = 所有可用
planId （選擇性）	預設值 = 所有可用
維度（選擇性）	預設值 = 所有可用
azureSubscriptionId （選擇性）	預設值 = 所有可用
reconStatus （選擇性）	預設值 = 所有可用

reconStatus的可能值：

ReconStatus	描述
提交	尚未由PC分析工具處理
接受	與PC分析匹配
拒絕	處理流程中遭到拒絕。請連絡Microsoft支持人員以調查原因。
失配	MarketplaceAPI 和合作夥伴中心分析的數量都是非零，但彼此不相符。

請求標頭：

內容類型	使用 application/json
x-ms-requestid	唯一字串值（最好是 GUID），用來追蹤來自用戶端的要求。如果未提供此值，則會在響應標頭中產生和提供一個值。
x-ms-correlationid	用於客戶端操作的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生和提供一個值。
授權	識別進行此 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
  }
]

提交

[
  {
    "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 禁止。授權令牌無效，或者未提供，或者提供時許可權不足。請務必提供有效的授權令牌。

開發和測試最佳做法

若要測試自定義計量排放，請實作與計量 API 的整合，為已發佈的 SaaS 供應專案建立一個方案，其中包含以每單位零價格定義的自定義維度。並將此供應專案發佈為預覽版，因此只有有限的使用者才能存取及測試整合。

您也可以使用私人方案，以將現有的即時優惠方案在測試期間的存取權限限制給有限的對象。

取得支援

請遵循合作夥伴中心商業市集計劃的支援中的指示，瞭解發行者支援選項，並使用 Microsoft 開啟支援票證。

如需計量服務 API 的詳細資訊，請參閱 Marketplace 計量服務 API 常見問題。

共用方式為

Marketplace 計量計費 API

TLS 1.2 強制執行說明

計量計費單次使用事件

反應

批次計量計費使用事件

反應

計量計費擷取使用事件記錄

反應

開發和測試最佳做法

取得支援

意見反應

其他資源

共用方式為

Marketplace 計量計費 API

TLS 1.2 強制執行說明

計量計費單次使用事件

反應

批次計量計費使用事件

反應

計量計費擷取使用事件記錄

反應

開發和測試最佳做法

取得支援

相關內容

意見反應

其他資源