您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Marketplace 计费 ApiMarketplace metered billing APIs

当发布者为要在合作伙伴中心发布的产品/服务创建自定义计量维度时,应使用按流量计费的 Api。The metered billing APIs should be used when the publisher creates custom metering dimensions for an offer to be published in Partner Center. 对于具有一个或多个具有自定义维度的计划,以发出使用情况事件,需要与按流量计费 Api 集成。Integration with the metered billing APIs is required for any purchased offer that has one or more plans with custom dimensions to emit usage events.

有关为 SaaS 创建自定义计量维度的详细信息,请参阅 saas计费。For more information on creating custom metering dimensions for SaaS, see SaaS metered billing.

有关使用托管应用计划为 Azure 应用程序提供创建自定义计量维度的详细信息,请参阅 配置 Azure 应用程序提供设置的详细信息For more information on creating custom metering dimensions for an Azure Application offer with a Managed app plan, see Configure your Azure application offer setup details.

强制执行 TLS 1.2 说明Enforcing TLS 1.2 Note

TLS 版本1.2 版本作为 HTTPS 通信的最小版本强制执行。TLS version 1.2 version is enforced as the minimal version for HTTPS communications. 请确保在代码中使用此 TLS 版本。Make sure you use this TLS version in your code. TLS 版本1.0 和1.1 已弃用,将拒绝连接尝试。TLS version 1.0 and 1.1 are deprecated and connection attempts will be refused.

计费单用量事件Metered billing single usage event

使用情况事件 API 应由发布服务器调用,以针对特定客户购买的计划) 的活动 (资源发出使用情况事件。The usage event API should be called by the publisher to emit usage events against an active resource (subscribed) for the plan purchased by the specific customer. 发布产品/服务时,将为发布者定义的计划的每个自定义维度单独发出使用情况事件。The usage event is emitted separately for each custom dimension of the plan defined by the publisher when publishing the offer.

对于一个日历日的每个小时,只能发出一个使用事件。Only one usage event can be emitted for each hour of a calendar day. 例如,在今天的8:15am,可以发出一个使用事件。For example, at 8:15am today, you can emit one usage event. 如果接受此事件,则将从今天上午9:00 接受下一次使用事件。If this event is accepted, the next usage event will be accepted from 9:00 am today. 如果在今天的8:15 和8:59:59 之间发送额外事件,则会被拒绝为重复。If you send an additional event between 8:15 and 8:59:59 today, it will be rejected as a duplicate. 应该累计一小时内消耗的所有单位,然后在单个事件中发出。You should accumulate all units consumed in an hour and then emit it in a single event.

每个资源的日历日每小时只能发出一个使用事件。Only one usage event can be emitted for each hour of a calendar day per resource. 如果在一小时内消耗了多个单位,则累积在一小时内消耗的所有单位,然后在单个事件中发出。If more than one unit is consumed in an hour, then accumulate all the units consumed in the hour and then emit it in a single event. 只能在过去24小时内发出使用情况事件。Usage events can only be emitted for the past 24 hours. 如果你在8:00 和8:59:59 之间的任何时间都发出使用事件 (并且该事件被接受) 并在8:00 与8:59:59 之间的同一天发送额外事件,则它将被拒绝为重复。If you emit a usage event at any time between 8:00 and 8:59:59 (and it is accepted) and send an additional event for the same day between 8:00 and 8:59:59, it will be rejected as a duplicate.

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

查询参数:Query parameters:

参数Paramter 建议Recommendation
ApiVersion 使用2018-08-31。Use 2018-08-31.

请求标头:Request headers:

Content-typeContent-type 使用 application/jsonUse application/json
x-ms-requestid 用于跟踪来自客户端的请求的唯一字符串值,最好是 GUID。Unique string value for tracking the request from the client, preferably a GUID. 如果未提供此值,则系统会生成一个值,并在响应标头中提供该值。If this value is not provided, one will be generated and provided in the response headers.
x-ms-correlationid 客户端上的操作的唯一字符串值。Unique string value for operation on the client. 此参数将来自客户端操作的所有事件与服务器端的事件关联起来。This parameter correlates all events from client operation with events on the server side. 如果未提供此值,将在响应标头中生成并提供一个值。If this value isn't provided, one will be generated and provided in the response headers.
authorization 标识进行此 API 调用的 ISV 的唯一访问令牌。A unique access token that identifies the ISV that is making this API call. "Bearer <access_token>"当发布服务器检索令牌值时,格式为,如中所述。The format is "Bearer <access_token>" when the token value is retrieved by the publisher as explained for

请求正文示例:Request body example:

{
  "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, can be integer or float value
  "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
}

备注

resourceId 对于 SaaS 应用和发出自定义计量的托管应用具有不同的含义。resourceId has different meaning for SaaS app and for Managed app emitting custom meter.

对于 Azure 应用程序托管应用计划, resourceId 是托管应用 resource group IdFor Azure Application Managed Apps plans, the resourceId is the Managed App resource group Id. 可在使用 Azure 管理的标识令牌中找到用于提取它的示例脚本。An example script for fetching it can be found in using the Azure-managed identities token.

对于 SaaS 产品/服务,resourceId 是 SaaS 订阅 ID。For SaaS offers, the resourceId is the SaaS subscription ID. 有关 SaaS 订阅的更多详细信息,请参阅列出订阅For more details on SaaS subscriptions, see list subscriptions.

响应Responses

代码:200Code: 200
没问题。OK. 已接受并记录在 Microsoft 端的使用情况,以便进行进一步的处理和计费。The usage emission was accepted and recorded on Microsoft side for further processing and billing.

响应负载示例:Response payload example:

{
  "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
}

代码:400Code: 400
请求错误。Bad request.

  • 提供的请求数据丢失或无效。Missing or invalid request data provided.
  • effectiveStartTime 过去24小时以上。effectiveStartTime is more than 24 hours in the past. 事件已过期。Event has expired.
  • SaaS 订阅未处于订阅状态。SaaS subscription is not in Subscribed status.

响应负载示例:Response payload example:

{
  "message": "One or more errors have occurred.",
  "target": "usageEventRequest",
  "details": [
    {
      "message": "The resourceId is required.",
      "target": "ResourceId",
      "code": "BadArgument"
    }
  ],
  "code": "BadArgument"
}

代码:403Code: 403

已禁止。Forbidden. 未提供授权令牌,该令牌无效或已过期。The authorization token isn't provided, is invalid or expired. 或者,请求尝试访问使用不同 Azure AD 应用 ID 发布的产品/服务的订阅,该订阅与用于创建授权令牌的 ID 不同。Or the request is attempting to access a subscription for an offer that was published with a different Azure AD App ID from the one used to create the authorization token.

代码:409Code: 409
冲突。Conflict. 已为指定的资源 ID (有效使用日期和小时)成功报告了使用事件。A usage event has already been successfully reported for the specified resource ID, effective usage date and hour.

响应负载示例:Response payload example:

{
  "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"
}

按流量计费的批次使用事件Metered billing batch usage event

Batch 用量事件 API 允许一次为多个已购买的资源发出使用事件。The batch usage event API allows you to emit usage events for more than one purchased resource at once. 它还允许您为同一资源发出几个使用事件,前提是它们适用于不同的日历小时。It also allows you to emit several usage events for the same resource as long as they are for different calendar hours. 单个批处理中的最大事件数为25。The maximal number of events in a single batch is 25.

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

查询参数:Query parameters:

参数Parameter 建议Recommendation
ApiVersion 使用2018-08-31。Use 2018-08-31.

请求标头:Request headers:

Content-typeContent-type 使用 application/jsonUse application/json
x-ms-requestid 用于跟踪来自客户端的请求的唯一字符串值,最好是 GUID。Unique string value for tracking the request from the client, preferably a GUID. 如果未提供此值,则系统会生成一个值,并在响应标头中提供该值。If this value is not provided, one will be generated, and provided in the response headers.
x-ms-correlationid 客户端上的操作的唯一字符串值。Unique string value for operation on the client. 此参数将来自客户端操作的所有事件与服务器端的事件关联起来。This parameter correlates all events from client operation with events on the server side. 如果未提供此值,则系统会生成一个值,并在响应标头中提供该值。If this value isn't provided, one will be generated, and provided in the response headers.
authorization 标识进行此 API 调用的 ISV 的唯一访问令牌。A unique access token that identifies the ISV that is making this API call. Bearer <access_token>当发布服务器检索令牌值时,格式为,如中所述。The format is Bearer <access_token> when the token value is retrieved by the publisher as explained for

请求正文示例:Request body example:

{
  "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, can be integer or float value
      "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
    }
  ]
}

备注

resourceId 对于 SaaS 应用和发出自定义计量的托管应用具有不同的含义。resourceId has different meaning for SaaS app and for Managed app emitting custom meter.

对于 Azure 应用程序托管应用计划, resourceId 是托管应用 resource group IdFor Azure Application Managed Apps plans, the resourceId is the Managed App resource group Id. 可在使用 Azure 管理的标识令牌中找到用于提取它的示例脚本。An example script for fetching it can be found in using the Azure-managed identities token.

对于 SaaS 产品/服务,resourceId 是 SaaS 订阅 ID。For SaaS offers, the resourceId is the SaaS subscription ID. 有关 SaaS 订阅的更多详细信息,请参阅列出订阅For more details on SaaS subscriptions, see list subscriptions.

响应Responses

代码:200Code: 200
没问题。OK. 已接受并记录在 Microsoft 端的 batch 使用情况,以便进行进一步的处理和计费。The batch usage emission was accepted and recorded on Microsoft side for further processing and billing. 返回响应列表,其中包含批处理中每个单独事件的状态。The response list is returned with status for each individual event in the batch. 应循环访问响应负载,以了解在批处理事件中发送的每个单独使用事件的响应。You should iterate through the response payload to understand the responses for each individual usage event sent as part of the batch event.

响应负载示例:Response payload example:

{
  "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 响应中引用状态代码的说明:Description of status code referenced in BatchUsageEvent API response:

状态代码Status code 说明Description
Accepted 已接受。Accepted.
Expired 使用已过期。Expired usage.
Duplicate 提供了重复的使用情况。Duplicate usage provided.
Error 错误代码。Error code.
ResourceNotFound 提供的使用资源无效。The usage resource provided is invalid.
ResourceNotAuthorized 你无权提供此资源的使用情况。You are not authorized to provide usage for this resource.
InvalidDimension 用于传递使用情况的维度对于此产品/服务或计划无效。The dimension for which the usage is passed is invalid for this offer/plan.
InvalidQuantity 传递的数量低于或等于0。The quantity passed is lower or equal to 0.
BadArgument 缺少输入,或输入格式不正确。The input is missing or malformed.

代码:400Code: 400
请求错误。Bad request. 批处理包含25个以上的使用情况事件。The batch contained more than 25 usage events.

代码:403Code: 403
已禁止。Forbidden. 未提供授权令牌,该令牌无效或已过期。The authorization token isn't provided, is invalid or expired. 或者,请求尝试访问使用不同 Azure AD 应用 ID 发布的产品/服务的订阅,该订阅与用于创建授权令牌的 ID 不同。Or the request is attempting to access a subscription for an offer that was published with a different Azure AD App ID from the one used to create the authorization token.

开发和测试最佳做法Development and testing best practices

若要测试自定义计量器,请实现与计量 API 的集成,为已发布的 SaaS 产品/服务创建计划,并在其中定义自定义维度,每个单位的价格为零。To test the custom meter emission, implement the integration with metering API, create a plan for your published SaaS offer with custom dimensions defined in it with zero price per unit. 并发布此产品/服务作为预览,因此只有受限用户才能访问和测试集成。And publish this offer as preview so only limited users would be able to access and test the integration.

你还可以将私有计划用于现有的实时服务,以限制在测试到有限受众的过程中对此计划的访问。You can also use private plan for an existing live offer to limit the access to this plan during testing to limited audience.

获取支持Get support

按照对 合作伙伴中心中的商业市场计划的支持 中的说明,了解发布者支持选项,并与 Microsoft 建立支持票证。Follow the instruction in Support for the commercial marketplace program in Partner Center to understand publisher support options and open a support ticket with Microsoft.

后续步骤Next steps

有关计量服务 Api 的详细信息,请参阅 Marketplace 计量服务 API 常见问题解答For more information on metering service APIs , see Marketplace metering service APIs FAQ.