本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 AWS Marketplace Metering Service 对容器产品配置自定义计量 **注意** 对于 Amazon EKS 部署，您的软件必须使用[服务账户的 IAM 角色（IRSA）](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)来签署对 [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) API 操作的 API 调用。不支持使用 [EKS 容器组身份](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)、节点角色或长期访问密钥。 对于 Amazon ECS 部署，您的软件必须使用 [Amazon ECS 任务 IAM](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) 角色来签署对 [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) API 操作的 API 调用。不支持使用节点角色或长期访问密钥。 对于 Amazon Bedrock AgentCore 运行时部署，您的软件必须使用[AgentCore 运行时执行角色](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-execution)来签署 API 操作的 [https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html)API 调用。不支持使用长期访问密钥。 AWS Marketplace 集装箱产品可以对每种产品多达 24 种不同的定价维度进行自定义计量。每个维度都可以具有与之相关的长期合同价格。要启用自定义计量，请将您的容器产品与 AWS Marketplace Metering Service 集成。您可以使用 [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)API 操作为该使用量定义自己的定价单位和自定义计量以 AWS 进行计费。以下部分将介绍如何为容器产品配置自定义计量。 价格维度在两个位置定义，一次是在 AWS Marketplace 管理门户 （卖家门户）创建产品时，另一次是在软件中执行 `MeterUsage` 操作时。此双因素方法可确保后续的产品在向公众提供之前按预期工作。 要设置自定义计量，您需要选择使用类别、单位类型和定价维度： + **用户类别** - 用户类别可帮助买家了解您的产品是什么以及如何使用它。 + **单位类型** - 单位类型定义计费的计量单位。例如，以 GBps 或为单位的带宽 MBps、以主机数量为单位的带宽，或者以 MB、GB 或 TB 为单位的数据。 + **定价维度**-定价维度表示您为其设置了单位价格的功能或服务（例如，用户、扫描CPUs、v 或已部署的代理）。定价维度是公开的。但是，您仍然可以为公开产品定义专属和自带许可 (BYOL) 优惠。请勿在计量记录中发送定价。您可以计量单位数量，我们将其与您在创建产品时定义的价格一起使用，以计算买家的账单。 如果您的产品定价不符合任何预定义类别或单位类型，您可以选择通用**单位**类别。然后，使用维度描述来描述单位是什么。 或者，您可以按您跟踪的属性将用量分发到分配中。分配以标签形式呈现给买家。这些标签允许买家按标签值查看按用量划分的费用。例如，如果您按用户收费，并且用户具有“部门”属性，则可以使用键为“部门”的标签创建使用分配，每个值一个分配。这不会更改您报告的价格、维度或总用量，但允许您的客户按与您的产品相应类别查看其成本。 我们建议您每小时发送一次计量记录。但是，您也可以汇总每日或每月的用量。如果您遇到中断，您可以聚合买家的软件用量，并在接下来的小时计量中发送。每小时不能发送多条记录。 有关将集装箱产品 AWS Marketplace Metering Service 的 API 与自定义计量定价集成的更多信息，请参阅*AWS Marketplace 卖家研讨会*的 “[与自定义计量集成](https://catalog.workshops.aws/mpseller/en-US/container/integrate-custom)” 实验室。 **重要** 免费试用和预付费权利按小时进行跟踪。因此，单独发送这些记录可能会导致买家被多收费用。 **Topics** + [自定义计量先决条件](#custom-metering-prereqs) + [测试 ECS 和 EKS 的 `MeterUsage` 集成](#testing-meterusage-integration) + [测试 MeterUsage 集成 AgentCore](#testing-agentcore-metering) + [`MeterUsage` 中的错误处理](#custom-metering-entitlement-error-handling) + [（可选）供应商计量标记](#container-vendor-metered-tagging) + [代码示例](#container-meter-code-example) + [使用自定义计量将您的容器产品与 AWS Marketplace Metering Service 和集成 适用于 Java 的 AWS SDK](java-integration-example-meterusage.md) ## 自定义计量先决条件 发布产品之前，您必须首先完成以下操作： 1. 在中创建新的容器产品 AWS Marketplace 管理门户，并记下其产品代码。 1. 为运行应用程序的任务、容器或 AgentCore 运行时终端节点使用 AWS Identity and Access Management (IAM) 角色，并获得调用所需的 IAM 权限`MeterUsage`。IAM 托管策略 `AWSMarketplaceMeteringRegisterUsage` 具有这些权限。有关该策略的更多信息，请参阅[ AWSMarketplaceMeteringFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSMarketplaceMeteringFullAccess.html)《*AWS 托管策略参考*》。 1. （可选）如果您想查看 AWS CloudTrail 日志记录，我们建议您在任务或 pod 定义中启用日志记录。 1. 使用您定义的所有定价维度的记录对 `MeterUsage` API 操作进行测试调用。 ## 测试 ECS 和 EKS 的 `MeterUsage` 集成 在将图片提交给发布之前，请使用该`MeterUsage`操作来 AWS Marketplace 测试您的集成。 通过在亚马逊弹性容器服务 (Amazon ECS) 或亚马逊 Elastic Kubernetes Service (Amazon EKS) 上运行您的产品，使用您用来发布商品的容器镜像调`MeterUsage`用。 AWS 账户 AWS Marketplace您的计量集成必须动态设置 AWS 区域，而不是对其进行硬编码。但是，在测试时，请至少在美国东部（弗吉尼亚北部）地区启动一个包含您的付费容器的 Amazon ECS 任务或 Amazon EKS Pod，以便 AWS Marketplace 运营团队可以使用该地区的日志验证您的工作。 **注意** 如果您的产品同时支持 Amazon ECS 和 Amazon EKS，则您只需在 Amazon EKS 中启动，我们便能验证您的集成。 在向公众发布产品之前和添加新维度之后，对每个维度进行测试。如果您没有发送与容器产品关联的每个维度的计量记录，则会导致错误并导致请求失败。 在使用所有必需的元数据和定价信息发布您的产品之前，您无法完全测试集成。如果需要， AWS Marketplace 目录运营团队可以验证您的计量记录是否收到。 ## 测试 MeterUsage 集成 AgentCore 在将图片提交给发布之前，请使用该`MeterUsage`操作来 AWS Marketplace 测试您的集成。 使用您上架商品时使用的 AWS 账户在 Amazon Bedrock AgentCore 上 AWS Marketplace运行您的商品，`MeterUsage`从容器图片中调用。您的计量集成必须动态设置 AWS 区域，而不是对其进行硬编码。但是，在测试时，请至少在美国东部（弗吉尼亚北部）地区启动一个包含您的付费容器的 Amazon Bedrock AgentCore 代理，以便 AWS Marketplace 运营团队可以使用该地区的日志验证您的工作。 您无需汇总每小时使用记录。每次调用代理时，都应针对该次调用的使用量调用 `MeterUsage` 操作。 您必须使用适用于您的语言的最新发布版本的 AWS SDK。这会自动使用自动生成的值填充 `ClientToken` 参数，以帮助确定幂等性。之前发布的未填充此字段的 SDK 将不适用于来自 Amazon Bedro AgentCore ck 内部的`MeterUsage`呼叫。由于网络问题，重试时必须重复使用完全相同的请求。这样做可以确保以幂等方式处理请求。 由于 Amazon Bedrock AgentCore 与其他容器产品之间的预期计量行为存在差异，因此我们不建议在亚马逊 Bedrock AgentCore 和亚马逊 ECS 或 EKS 上共享相同的容器映像。 ## `MeterUsage` 中的错误处理 容器启动时调用 `MeterUsage`，并将 `DryRun` 参数设为 true，以此验证计量集成是否正常工作。如果您的容器映像与 `MeterUsage` 操作集成并在容器启动时收到 `ThrottlingException` 之外的异常，您应终止容器以防止未经授权的使用。 仅在初始调用 `MeterUsage` 时引发 `ThrottlingException` 以外的异常。即使客户在任务或容器仍在 AgentCore 运行时取消订阅，来自同一 Amazon ECS 任务或 Amazon EKS 容器或运行时终端节点的后续调用也不会抛出`CustomerNotSubscribedException`。这些客户在取消订阅并跟踪其使用情况后仍需支付运行容器的费用。 有关常见错误[MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)的详细说明，请参阅 *AWS Marketplace Metering Service API 参考*中的`MeterUsage`。每种 AWS SDK 编程语言都有一套错误处理指南，您可以参考这些指南以获取更多信息。 ## （可选）供应商计量标记 供应商计量标签可帮助独立软件供应商 (ISVs) 让购买者更精细地了解其软件使用情况，并可以帮助他们进行成本分配。 **注意** Amazon Bedrock 产品的计量请求不支持供应商计量标签。 AgentCore 您可通过多种方式为买家的软件使用情况添加标签。一种方法是先询问买家他们希望在成本分配中看到什么。然后，您可以在为买家帐户跟踪的属性之间分配使用情况。属性的示例包括 `AccountId`、`Business Unit`、`Cost Centers`，以及您的产品的其他相关元数据。这些属性作为标签展示给买家。使用标签，买家可以在 AWS 账单控制台（[https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/)）中查看按标签值划分为使用量的费用。供应商计量标记不会更改您报告的价格、维度或总用量。它允许您的客户按您产品的相应类别查看成本。 在常见情形中，买家会通过一个 AWS 账户订阅您的产品。买家还有许多与同一产品订阅相关的用户。您可以使用具有 `AccountId` 键的标签创建用量分配，然后将用量分配给每个用户。在这种情况下，买家可以在其账单与成本管理控制台中激活 `AccountId` 标签并分析个人用户的使用情况。 ### 卖家体验 卖家可以汇总具有相同标签集的资源的计量记录，而不是汇总所有资源的使用情况。例如，卖家可以构造包含不同的 `UsageAllocations` 存储桶的计量记录。每个存储桶代表一组标签的 `UsageQuantity`，例如 `AccountId` 和 `BusinessUnit`。 在下图中，**资源 1** 具有一组唯一的 `AccountId` 和 `BusinessUnit` 标签，并作为单个条目出现在**计量记录**中。 **资源 2** 和**资源 3** 都具有相同的 `AccountId` 标签 `2222` 和相同的 `BusinessUnit` 标签 `Operations`。因此，它们在**计量记录**中合并为一个 `UsageAllocations` 条目。 ![该图显示了供应商计量标签如何合并用量数据。三个具有不同 AccountIds 和的资源（资源 1、2 和 3）在发送到 M AWS arketplace 计量服务 BusinessUnit 之前，将 UsageAllocations 按分组 AccountId 并整合到单个计量记录中。 BusinessUnits](http://docs.aws.amazon.com/zh_cn/marketplace/latest/userguide/images/seller-vendor-meter-tag.png) 卖家还可以将没有标签的资源组合成一个包含分配用量的 `UsageAllocation`，然后将其作为 `UsageAllocations` 中的一个条目发送。 限制包括： + 标签数 – 5 + `UsageAllocations`（基数）的大小 – 2500 验证包括： + 标签键和值允许使用的字符 — a-zA-Z 0-9\+-= 。 \_:\\ /@ + `UsageAllocation` 列表中的最大标签数 – 5 + 两个 `UsageAllocations` 的标签不能相同（也就是说，标签键和值的组合相同）。如果是这样的话，他们必须使用相同的 `UsageAllocation`。 + `UsageAllocation` 的 `AllocatedUsageQuantity` 之和必须等于 `UsageQuantity`，即聚合用量。 ### 买家体验 下表显示了买家激活 `AccountId` 和 `BusinessUnit` 供应商标签后的买家体验示例。 在此示例中，买家可以在其**成本使用报告**中看到分配的用量。供应商计量标签使用前缀 `“aws:marketplace:isv”`。在账单与成本管理中，买家可以再**成本分配标签**下的 **AWS生成的成本分配标签**中激活它们。 **成本使用报告**的第一行和最后一行与卖家向 Metering Service 发送的内容相关（如 [卖家体验](#container-vendor-metered-tag-seller) 示例所示）。 **成本使用报告（简化）** | ProductCode | 买家 | UsageDimension | UsageQuantity | `aws:marketplace:isv:AccountId ` | `aws:marketplace:isv:BusinessUnit` | | --- | --- | --- | --- | --- | --- | | xyz | 111122223333 | 网络：每 (GB) 检查一次 | 70 | 2222 | 运营 | | xyz | 111122223333 | 网络：每 (GB) 检查一次 | 30 | 3333 | 财务 | | xyz | 111122223333 | 网络：每 (GB) 检查一次 | 20 | 4444 | IT | | xyz | 111122223333 | 网络：每 (GB) 检查一次 | 20 | 5555 | 市场营销 | | xyz | 111122223333 | 网络：每 (GB) 检查一次 | 30 | 1111 | 市场营销 | 有关代码示例，请参阅 [带有用量分配标签的 `MeterUsage` 代码示例（可选）](#container-meterusage-code-example)。 ## 代码示例 以下代码示例旨在帮助您将容器产品与发布和维护产品 AWS Marketplace APIs 所需的产品集成。 ### 带有用量分配标签的 `MeterUsage` 代码示例（可选） 以下代码示例与具有消费定价模式的容器产品相关。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 Metering Service API 参考[MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)*中的。 ### 响应示例 ``` { "MeteringRecordId": "string" } ```