Marketplace 計量計費 API

發行項
01/12/2024

當發行者建立自定義計量維度以供合作夥伴中心發佈的供應專案時，應該使用計量計費 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。

要求標頭：

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 應用程式受控應用程式方案，resourceId是受控應用程式 resource group Id。如需擷取它的範例腳本，請參閱使用 Azure 受控識別令牌。

針對 SaaS 供應專案， resourceId 是 SaaS 訂用帳戶標識碼。如需 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

禁止：未提供授權令牌、無效或已過期。或者，要求嘗試存取以不同 Microsoft Entra 應用程式識別碼發行之供應專案的訂用帳戶，而該供應專案與用來建立授權令牌的供應專案相同。

程序代碼：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。

發佈：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。驗證策略中的受控應用程式。

注意

在要求主體中，資源標識碼對於 SaaS 應用程式和發出自定義計量的 Azure 受控應用程式有不同的意義。 SaaS 應用程式的資源識別碼為 resourceID。 Azure 應用程式 Managed Apps 方案的資源識別碼為 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
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"
    }
  ]
}

API 回應中 BatchUsageEvent 參考的狀態代碼描述：

狀態碼	描述
`Accepted`	接受。
`Expired`	使用量已過期。
`Duplicate`	提供的使用量重複。
`Error`	錯誤碼。
`ResourceNotFound`	提供的使用量資源無效。
`ResourceNotAuthorized`	您無權提供此資源的使用量。
`ResourceNotActive`	資源已暫停或從未啟用。
`InvalidDimension`	傳遞使用量的維度對於此供應專案/方案而言無效。
`InvalidQuantity`	傳遞的數量較低或等於 0。
`BadArgument`	輸入遺失或格式不正確。

程序代碼：400
不正確的要求。批次包含超過25個使用事件。

程序代碼：403
禁止：未提供授權令牌、無效或已過期。或者，要求嘗試存取以不同 Microsoft Entra 應用程式識別碼發行之供應專案的訂用帳戶，而該供應專案與用來建立授權令牌的供應專案相同。

計量計費擷取使用量事件

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

取得： 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 （選擇性）	預設值 = 所有可用
維度（選擇性）	預設值 = 所有可用
azureSubscriptionId （選擇性）	預設值 = 所有可用
reconStatus （選擇性）	預設值 = 所有可用

對帳狀態的可能值：

ReconStatus	描述
已提交	計算機分析尚未處理
已接受	與電腦分析相符
已拒絕	管線中遭到拒絕。請連絡 Microsoft 支援服務以調查原因。
失配	MarketplaceAPI 和合作夥伴中心分析數量都是非零，但不符合

要求標頭：

內容類型	使用 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 應用程式識別碼發行之供應專案的訂用帳戶，而該供應專案與用來建立授權令牌的供應專案相同。

開發和測試最佳做法

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

您也可以針對現有的即時供應專案使用私人方案，將測試期間此方案的存取限制為有限的物件。

取得支援

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

下一步

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

Marketplace 計量計費 API

強制執行 TLS 1.2 附注

計量計費單一使用量事件

回覆

計量計費批次使用量事件

回覆

計量計費擷取使用量事件

回覆

開發和測試最佳做法

取得支援

下一步

意見反應

意見反應

其他資源