本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 AMI 产品配置自定义计量 AWS Marketplace Metering Service
<a name="custom-metering-with-mp-metering-service"></a>

**注意**  
对于采用自定义计量定价的基于 AMI 的产品，您的软件必须使用附加到亚马逊 EC2 实例的 Amazon Elastic Compute Cloud 的 IAM 角色的临时 AWS 证书调用 [MeterUsage API](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html)。不支持使用长期访问密钥。

AWS Marketplace Metering Service 是一项定价和计量功能，您可以利用它根据使用类别直接为其软件收费。有五种使用类别：用户、数据、带宽、主机或单元。您可以将 Metering Service 与基于亚马逊机器映像 (AMI)、基于容器和基于软件即服务 (SaaS) 的产品配合使用。以下各节提供有关如何使用 AWS Marketplace Metering Service 配置自定义计量的信息。

使用 AWS Marketplace Metering Service 可以启用多种新方案。例如，如果您的软件监控主机，则您可以对监控的每个主机收费。您可以根据主机大小制定不同价格，并根据每小时监控的并发主机数量收费。与此类似，如果软件允许组织中的多个用户登录，您可以按用户数收费。每小时，将针对预配置的总用户数对客户收取一次费用。

有关更多信息，请参阅《[AWS Marketplace Metering Service API 参考](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html)》**。

有关将基于 AMI 的产品 AWS Marketplace Metering Service 的 API 与自定义计量定价集成的更多信息，请参阅*AWS Marketplace 卖家研讨*会的[列出按定制单位定价的 AMI 产品](https://catalog.workshops.aws/mpseller/en-US/ami/list-ami-custom-units)实验室。

**Topics**
+ [要求](#metering-service-requirements)
+ [调用 AWS Marketplace Metering Service](#call-aws-marketplace-metering-service)
+ [故障处理](#important-information-about-failure-handling)
+ [限制](#limitations)
+ [代码示例](#ami-metering-code-example)

## 要求
<a name="metering-service-requirements"></a>

使用 Metering Service 的所有基于 AMI 的软件必须满足以下要求：
+ 您的软件必须 AWS Marketplace 通过亚马逊系统映像 (AMI) 启动。
+ 如果您有现有产品 AWS Marketplace，则必须提交新的 AMI 并创建新产品才能启用此功能。
+ 所有软件都必须使用 AWS Identity and Access Management (IAM) 角色进行配置。最终客户必须将 IAM 角色添加到用户正在预置软件的 Amazon Elastic Compute Cloud (Amazon EC2) 实例。通过部署软件时，使用 IAM 角色是可选的 AWS Marketplace。部署 AWS Marketplace Metering Service 软件时，这是必需的。
+ 您的软件必须能够以某种方式确定使用情况。

## 调用 AWS Marketplace Metering Service
<a name="call-aws-marketplace-metering-service"></a>

 您的软件必须每小时调用一次 Metering Service，并记录该小时的用量值。

 当你的软件启动 minute-of-the-hour时，它应该记录它的启动时间。这称为*启动时刻*。在每小时的启动时刻，您的软件必须确定该小时的用量值并调用 Metering Service。有关如何获取此值的信息，请参阅[修改软件以使用 Metering Service](https://docs.aws.amazon.com/marketplace/latest/userguide/custom-metering-pricing-ami-products.html#modifying-your-software-to-use-the-metering-service)。

 要在每小时的启动时刻唤醒，您的软件必须使用以下方法之一：
+  您的软件中的线程。
+  随实例或软件启动的进程守护程序。
+  在应用程序启动期间配置的 cron 作业。
**注意**  
 您的软件必须使用在客户的实例上配置的 IAM 角色调用 AWS Marketplace Metering Service，并指定使用维度和数量。

您的软件可以使用软件 AWS 开发工具包调用 AWS Marketplace 计量服务，类似于以下示例实现：

1. 使用实例配置文件创建服务客户端。这需要使用为 EC2 实例配置的角色。该开发工具包自动刷新角色凭证。

1. 每小时读取一次您的软件配置和状态，以确定该小时的用量值。这可能包括收集 value-per-dimension.

1. 在开发工具包客户端，使用以下参数调用 `meterUsage` 方法（为每个具有用量的维度额外调用一次）：
   + `timestamp` – 记录的小时时间戳（UTC）。
   + `productCode` – 分配给软件的产品代码。
   + `dimension` – 分配给软件的维度。
   + `quantity` – 该小时的用量值。
   + `allocations` –（可选）您可以为所跟踪的属性的用量提供分配。这些分配必须与记录中的总消耗量相加。对于买家来说，这些标签在他们的计费工具（例如 AWS 账单与成本管理 控制台）中显示为潜在的成本分配标签。买家必须激活其账户中的标签才能使用这些标签追踪成本。

此外，您的软件还必须调用区域中的 AWS Marketplace Metering Service 端点。您的产品必须设置了正确的区域端点，以便 `us-east-1` 将记录发送到 `us-east-1` 端点，`us-west-2` 将记录发送到 `us-west-2` 端点。进行区域中调用为买家提供更稳定的体验，并防止存在不相关的区域而可能影响在其他区域中运行的软件。

在将计量记录发送到该服务时，您必须连接到您的区域中的 AWS Marketplace Metering Service。使用 `getCurrentRegion()` 帮助程序方法确定 EC2 实例运行的区域，然后将此区域信息传递给 `MeteringServiceClient` 构造函数。如果您未在 SDK 构造函数 AWS 区域 中指定，则使用默认`us-east-1`区域。如果您的应用程序尝试对该服务进行跨区域调用，将拒绝调用。有关更多信息，请参阅[确定应用程序的当前区域](https://java.awsblog.com/post/Tx3GBOIEN1JJMQ5/Determining-an-Application-s-Current-Region)和 [getCurrentRegion()](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/regions/Regions.html#getCurrentRegion())。

## 故障处理
<a name="important-information-about-failure-handling"></a>

您的产品必须将计量记录发送到该服务 (公有 Internet 端点)，以便可以捕获该用量和进行计费。由于客户可能使用某种方式修改网络设置而导致无法传送您的计量记录，您的产品应选择一个故障模式以处理这种情况。

**注意**  
某些计量失败可能是连接时出现的暂时性问题 AWS Marketplace Metering Service。 AWS Marketplace 强烈建议实施最长 30 分钟的重试，并以指数级退缩，以避免短期中断或网络问题。

通常，软件可能在发生故障时打开 (提供一条警告消息，但保留完整功能) 或在发生故障时关闭 (在应用程序中禁用所有功能，直到重新建立连接)。您可以选择在发生故障时打开、在发生故障时关闭或您的应用程序特定的模式。在发生计量故障两小时后内，强烈建议您禁止在发生故障时关闭。

例如，如果在发生故障时部分打开，您可以继续允许访问软件，但不允许买家修改软件设置。或者，买家仍然可以访问软件，但无法创建额外的用户。您的软件负责定义和实施该故障模式。在提交您的 AMI 时，必须包含您的软件的故障模式，以后无法对其进行更改。

## 限制
<a name="limitations"></a>

 在设计和提交支持 Metering Service 的软件时，请务必记住以下限制：
+ **客户的 IAM 角色和互联网网关要求** - 您的客户必须拥有互联网网关，并且必须使用带特定权限的 IAM 角色启动软件。有关更多信息，请参阅 [AWS Marketplace 计量和授权 API 权限](iam-user-policy-for-aws-marketplace-actions.md)。如果未满足这两个条件，则您的软件无法连接到 Metering Service。
+  **无法将新的使用类别添加到现有 Metering Service 产品，也无法更改这些类别** - 一旦客户订阅您的软件产品，即表示他们同意条款和条件。使用 Metering Service 更改产品中的使用类别需要新产品和新订阅。
+ **无法将新的维度添加到现有 Metering Service 产品，也无法更改这些纬度** - 一旦客户订阅您的软件产品，即表示他们同意条款和条件。使用 Metering Service 更改产品中的维度需要新产品和新订阅。您*可以*为现有产品添加新维度，上限为 24 个。
+  **缺少免费试用和年度订阅** - Metering Service 产品在启动时不支持免费试用和年度订阅。
+  **多实例或基于集群的部署注意事项** - 一些软件将作为多实例部署的一部分部署。在设计您的软件时，请考虑测量用量的方式和位置以及发出计量记录的位置。

## 代码示例
<a name="ami-metering-code-example"></a>

以下代码示例旨在帮助您将 AMI 产品与发布和维护产品 AWS Marketplace APIs 所需的产品集成。

### 带有用量分配标签的 `MeterUsage`（可选）
<a name="ami-meterusage-code-example"></a>

以下代码示例与具有消费定价模式的 AMI 产品相关。Python 示例将带有相应使用量分配标签的计量记录发送给您的客户 AWS Marketplace ，以向您的客户收取 pay-as-you-go费用。

```
# NOTE: Your application will need to aggregate usage for the 
#       customer for the hour and set the quantity as seen below. 
# AWS Marketplace can only accept records for up to an hour in the past. 
#
# productCode is supplied after the AWS Marketplace Ops team has 
# published the product to limited

# Import AWS Python SDK
import boto3
import time

usageRecord = [
    { 
        "AllocatedUsageQuantity": 2, 
        "Tags": 
            [ 
                { "Key": "BusinessUnit", "Value": "IT" },
                { "Key": "AccountId", "Value": "123456789" },
            ]

    },
    { 
        "AllocatedUsageQuantity": 1, 
        "Tags": 
            [ 
                { "Key": "BusinessUnit", "Value": "Finance" },
                { "Key": "AccountId", "Value": "987654321" },
            ]

    }
]

marketplaceClient = boto3.client("meteringmarketplace")

response = marketplaceClient.meter_usage(
    ProductCode="testProduct",
    Timestamp=int(time.time()),
    UsageDimension="Dimension1",
    UsageQuantity=3,
    DryRun=False,
    UsageAllocations=usageRecord 
)
```

有关更多信息`MeterUsage`，请参阅《*AWS Marketplace 计量服务 API 参考*》[MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)中的。

### 响应示例
<a name="ami-meterusage-code-response"></a>

```
{ "MeteringRecordId": "string" }
```