市场按流量计费的 API

项目
03/12/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>"`，前提是发布者按以下说明检索令牌值：通过 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 订阅 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 未授权。授权令牌无效或已过期。请求尝试访问某个促销产品的 SaaS 订阅，但发布该产品时使用的 Microsoft Entra 应用 ID 与创建身份验证令牌时使用的 ID 不同。

代码：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，可以一次性为多个购买的资源发出使用情况事件。它还允许你为同一资源发出多个使用事件，前提是它们适用于不同的日历小时数。单个批中的最大事件数为 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>`，前提是发布者按以下说明检索令牌值：通过 HTTP POST 获取令牌中针对 SaaS 的说明。在身份验证策略中托管的应用程序。

注意

在请求正文中，资源标识符对 SaaS 应用和发出自定义计量的 Azure 托管应用有不同的含义。 SaaS 应用的资源标识符 resourceID。 Azure 应用程序托管应用计划的资源标识符 resourceUri。有关资源标识符的详细信息，请参阅 Azure 市场按流量计费 - 在提交使用事件时选择正确的 ID。

对于 SaaS 产品/服务，resourceId 是 SaaS 订阅 ID。有关 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 应用 ID 不同于创建身份验证令牌时所用的 ID。

代码：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>`。有关详细信息，请参阅：通过 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 已禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

开发和测试最佳做法

若要测试自定义计量排放，请实现与计量 API 的集成，为已发布的 SaaS 产品/服务创建一个计划，其中包含以每单位零价格定义的自定义维度。并将此产品/服务发布为预览版，以便只有有限的用户才能访问和测试集成。

还可以针对现有的已发布产品/服务采用专用计划，以在测试期间将该计划的访问权限限制在特定受众范围内。

获取支持

请遵循合作伙伴中心中商业市场计划支持中的说明，了解发布者支持选项，并向 Microsoft 提交支持工单。

有关计量服务 API 的详细信息，请参阅市场计量服务 API 常见问题解答。

通过

市场按流量计费的 API

强制实施 TLS 1.2 的说明

按流量计费的单次使用事件

反应

按流量计费的批处理使用事件

反应

计量计费检索使用事件

反应

开发和测试最佳做法

获取支持

反馈

其他资源

通过

市场按流量计费的 API

强制实施 TLS 1.2 的说明

按流量计费的单次使用事件

反应

按流量计费的批处理使用事件

反应

计量计费检索使用事件

反应

开发和测试最佳做法

获取支持

相关内容

反馈

其他资源