Marketplace 計量計費 API

發行項
01/31/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 與建立驗證權杖時使用的不同。

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

錯誤代碼：401 未經授權。授權令牌無效或已過期。要求嘗試存取一個 SaaS 訂閱，其供應專案是用與建立驗證令牌不同的 Microsoft Entra 應用程式標識符發佈的。

代碼：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	描述
提交	計算機分析尚未處理
接受	與個人電腦分析相符
拒絕	處理流程中遭到拒絕。請連絡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
  }
]

狀態代碼

錯誤碼：401 未經授權。授權令牌無效或已過期。請求正嘗試存取一個 SaaS 訂閱，此訂閱的供應專案是以一個與建立驗證令牌所使用的 Microsoft Entra 應用程式 ID 不同的 ID 發佈。

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

開發和測試最佳做法

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

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

取得支援

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

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

共用方式為

Marketplace 計量計費 API

TLS 1.2 強制執行說明

計量計費單次使用事件

反應

計量計費批次使用量事件

反應

計量計費擷取使用量事件

反應

開發和測試最佳做法

取得支援

意見反應

其他資源

共用方式為

Marketplace 計量計費 API

TLS 1.2 強制執行說明

計量計費單次使用事件

反應

計量計費批次使用量事件

反應

計量計費擷取使用量事件

反應

開發和測試最佳做法

取得支援

相關內容

意見反應

其他資源