市场按流量计费 API

项目
06/14/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 订阅 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"
}

代码：403

已禁止。未提供授权令牌，令牌无效或已过期。或者，该请求尝试访问使用与用于创建授权令牌的套餐不同的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，可一次性发出多项已购资源的使用事件。它还允许你为同一资源发出多个使用事件，前提是它们适用于不同的日历小时数。一个批次中的最大事件数为 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）。身份验证策略（针对托管应用程序）。

注意

在请求正文中，资源标识符对于 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 个。

代码：403
已禁止。未提供授权令牌，令牌无效或已过期。或者，该请求尝试访问使用与用于创建授权令牌的套餐不同的Microsoft Entra 应用 ID 发布的套餐的订阅。

按流量计费检索使用情况事件

你可以调用使用情况事件 API 来获取使用情况事件的列表。 ISV 可以使用此 API 来查看在特定的可配置时间段内已发布的使用情况事件，以及在调用 API 时这些事件的状态。

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

查询参数：

参数	建议
ApiVersion	使用 2018-08-31。
usageStartDate	ISO8601 格式的日期/时间。例如，2020-12-03T15:00 或 2020-12-03
UsageEndDate（可选）	ISO8601 格式的日期/时间。默认值 = 当前日期
offerId（可选）	默认值 = 所有可用项
planId（可选）	默认值 = 所有可用项
dimension（可选）	默认值 = 所有可用项
azureSubscriptionId（可选）	默认值 = 所有可用项
reconStatus（可选）	默认值 = 所有可用项

reconStatus 的可能值：

ReconStatus	说明
已提交	尚未由 PC Analytics 进行处理
已接受	已使用 PC Analytics 进行匹配
已拒绝	已在管道中被拒绝。请联系 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 应用 ID 发布的套餐的订阅。

开发和测试最佳做法

要测试自定义计量的发出情况，请实现与计量 API 的集成，为已发布的 SaaS 产品/服务创建计划并定义自定义维度，其中每单位价格为零。然后将此产品/服务作为预览版发布，以便只有有限数量的用户能够访问和测试集成。

还可对现有的有效产品/服务使用专用计划，在测试期间只有有限数量的用户可访问该计划。

获取支持

请遵照合作伙伴中心商业市场计划的支持中的说明，了解发布者支持选项并使用 Microsoft 启动支持工单。

要详细了解计量服务 API，请参阅市场计量服务 API 常见问题解答。

通过

市场按流量计费 API

强制使用 TLS 1.2 说明

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

响应

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

响应

按流量计费检索使用情况事件

响应

开发和测试最佳做法

获取支持

反馈

其他资源

通过

市场按流量计费 API

强制使用 TLS 1.2 说明

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

响应

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

响应

按流量计费检索使用情况事件

响应

开发和测试最佳做法

获取支持

相关内容

反馈

其他资源