本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS Marketplace Metering Service 設定容器產品的自訂計量 **注意** 對於 Amazon EKS 部署，您的軟體必須使用[服務帳戶 (IRSA) 的 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)來簽署 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 呼叫。不支援使用 [EKS Pod Identity](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) 角色來簽署 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 呼叫。不支援使用節點角色或長期存取金鑰。 對於 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 測量的資料。 + **定價維**度 – 定價維度代表您已設定每單位價格的功能或服務 （例如使用者、掃描、vCPUs 或部署的代理程式）。定價維度為公有。不過，您仍然可以為公有產品定義私有和自攜授權 (BYOL) 優惠。請勿在計量記錄中傳送定價。您可以測量單位數量，並使用它以及您建立產品以計算買方帳單時定義的價格。 如果您的產品定價不符合任何預先定義的類別或單位類型，您可以選擇一般**單位**類別。然後，使用維度描述來描述什麼是單位。 或者，您可以根據您追蹤的屬性，將用量分配到配置。配置會以標籤表示給買方。這些標籤可讓買方檢視依標籤值分割為用量的成本。例如，如果您由使用者收費，且使用者具有「部門」屬性，則可以使用索引鍵為「部門」的標籤建立用量配置，每個值一個配置。這不會變更您報告的價格、維度或總用量，但可讓您的客戶依適合您產品的類別檢視其成本。 建議您每小時傳送計量記錄。不過，您也可以彙總每日或每月期間的用量。如果您遇到中斷，您可以彙總買方軟體的使用，並在下列時間計量中傳送。您無法每小時傳送超過一筆記錄。 如需整合容器產品的 AWS Marketplace Metering Service API 與自訂計量定價的詳細資訊，請參閱 [與賣方研討會的自訂計量實驗室整合](https://catalog.workshops.aws/mpseller/en-US/container/integrate-custom)。 *AWS Marketplace * **重要** 免費試用和預付權利會每小時追蹤一次。因此，在 中分別傳送這些記錄可能會導致買方過度收費。 **Topics** + [自訂計量先決條件](#custom-metering-prereqs) + [測試 ECS 和 EKS 的`MeterUsage`整合](#testing-meterusage-integration) + [測試 AgentCore 的 MeterUsage 整合](#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. 將 AWS Identity and Access Management (IAM) 角色用於執行應用程式的任務、Pod 或 AgentCore 執行期端點，並具有呼叫 所需的 IAM 許可`MeterUsage`。IAM 受管政策`AWSMarketplaceMeteringRegisterUsage`具有這些許可。如需政策的詳細資訊，請參閱《 *AWS 受管政策參考*》中的 [ AWSMarketplaceMeteringFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSMarketplaceMeteringFullAccess.html)。 1. （選用） 如果您想要查看 AWS CloudTrail 記錄，建議您在任務或 Pod 定義中啟用記錄。 1. 使用您定義的所有定價維度的記錄測試呼叫 `MeterUsage` API 操作。 ## 測試 ECS 和 EKS 的`MeterUsage`整合 使用 `MeterUsage`操作來測試整合，然後再將映像提交至 AWS Marketplace 進行發佈。 透過在 Amazon Elastic Container Service (Amazon ECS) 或 Amazon Elastic Kubernetes Service (Amazon EKS) 上執行您的產品，並使用 AWS 帳戶 在 上列出產品，`MeterUsage`從容器映像呼叫 AWS Marketplace。您的計量整合必須動態設定 AWS 區域，而不是硬式編碼。不過，在測試時，請至少啟動一個 Amazon ECS 任務或包含美國東部 （維吉尼亞北部） 區域中已付費容器的 Amazon EKS Pod，以便 AWS Marketplace 操作團隊可以驗證您在該區域中使用日誌的工作。 **注意** 如果您的產品同時支援 Amazon ECS 和 Amazon EKS，您只需要在 Amazon EKS 中啟動，我們就能驗證您的整合。 在將產品啟動到公有環境之前，以及在新增維度之後，測試每個維度。如果您未針對與容器產品相關聯的每個維度傳送計量記錄，則會導致請求失敗的錯誤。 在使用所有必要中繼資料和定價資訊發佈產品之前，您無法完整測試整合。如果請求， AWS Marketplace 目錄操作團隊可以驗證是否收到您的計量記錄。 ## 測試 AgentCore 的 MeterUsage 整合 使用 `MeterUsage`操作來測試整合，然後再將映像提交至 AWS Marketplace 進行發佈。 使用用來列出產品的 AWS 帳戶在 Amazon Bedrock AgentCore 上執行您的產品，`MeterUsage`從容器映像呼叫 AWS Marketplace。您的計量整合必須動態設定 AWS 區域，而不是硬式編碼。不過，在測試時，請至少啟動一個 Amazon Bedrock AgentCore 代理程式，其中包含您在美國東部 （維吉尼亞北部） 區域的付費容器，以便 AWS Marketplace 營運團隊可以驗證您在該區域中使用日誌的工作。 您不需要彙總每小時用量記錄。`MeterUsage` 在每次客服人員調用時呼叫該調用的使用量。 您必須使用最新版本的 AWS SDK 做為您的語言。這會自動將自動產生的值填入 `ClientToken` 參數，以協助處理冪等性。未填入此欄位的舊版軟體開發套件不適用於來自 Amazon Bedrock AgentCore 的`MeterUsage`呼叫。由於網路問題，您必須在重試時重複使用相同的確切請求。這樣做可確保以等冪方式處理請求。 由於 Amazon Bedrock AgentCore 和其他容器產品之間的預期計量行為差異，我們不建議共用相同的容器映像，以便在 Amazon Bedrock AgentCore 和 Amazon ECS 或 EKS 上使用。 ## 的錯誤處理 `MeterUsage` 呼叫在容器啟動時將 `DryRun` 參數`MeterUsage`設定為 true，以驗證計量整合是否正常運作。如果您的容器映像與 `MeterUsage`操作整合，並收到容器啟動`ThrottlingException`時 以外的例外狀況，您應該終止容器，以防止未經授權的使用。 以外的例外僅在對 的初始呼叫中`ThrottlingException`擲回`MeterUsage`。來自相同 Amazon ECS 任務或 Amazon EKS Pod 或 AgentCore 執行期端點的後續呼叫不會擲回 `CustomerNotSubscribedException`，即使客戶在任務或 Pod 仍在執行時取消訂閱。這些客戶在取消訂閱並追蹤其用量後，仍需支付執行中容器的費用。 如需 常見錯誤的詳細說明，請參閱 *AWS Marketplace Metering Service API 參考*中的 [MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)`MeterUsage`。每個 AWS SDK 程式設計語言都有一組錯誤處理準則，如需其他資訊，請參閱這些準則。 ## （選用） 廠商計量標記 廠商計量標記可協助獨立軟體廠商 (ISVs) 為買方提供更精細的軟體用量洞察，並協助他們執行成本分配。 **注意** Amazon Bedrock AgentCore 產品的計量請求不支援廠商計量標記。 您有多種方法可以標記買方的軟體用量。其中一個是先詢問您的買方，他們想要在成本分配中看到什麼。然後，您可以將用量分割到您追蹤買方帳戶的屬性。屬性的範例包括 `AccountId`、`Cost Centers`、 `Business Unit`和您產品的其他相關中繼資料。這些屬性會以標籤的形式公開給買方。使用標籤，買方可以在帳單 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和 BusinessUnits 的三個資源 （資源 1、2 和 3) 會合併為單一計量記錄，並依 AccountId 和 BusinessUnit 分組 UsageAllocations，再傳送至 AWS Marketplace Metering Service。](http://docs.aws.amazon.com/zh_tw/marketplace/latest/userguide/images/seller-vendor-meter-tag.png) 賣方也可以將沒有標籤的資源合併為`UsageAllocation`具有配置用量數量的單一資源，並將其做為 中的其中一個項目傳送`UsageAllocations`。 限制包括： + 標籤數量 – 5 + 大小 `UsageAllocations`（基數） – 2，500 驗證包括： + 標籤索引鍵和值允許的字元 – a-zA-Z0-9\+ -=.\_：\\/@ + 跨`UsageAllocation`清單的標籤上限 – 5 + 兩個 `UsageAllocations` 不能有相同的標籤 （也就是標籤索引鍵和值的相同組合）。如果是這種情況，他們必須使用相同的 `UsageAllocation`。 + `AllocatedUsageQuantity` 的 總和`UsageAllocation`必須等於 `UsageQuantity`，即彙總用量。 ### 買方體驗 下表顯示買方啟用 `AccountId`和`BusinessUnit`廠商標籤後買方體驗的範例。 在此範例中，買方可以在其**成本用量報告中看到配置的用量**。廠商計量的標籤使用字首 `“aws:marketplace:isv”`。買方可以在帳單和成本管理、**成本分配標籤**、 **AWS產生的成本分配標籤**下啟用它們。 **成本用量報告**的第一列和最後一列與賣方傳送到計量服務的內容相關 （如[賣方體驗](#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 | Marketing | | xyz | 111122223333 | 網路：每個 (GB) 已檢查 | 30 | 1111 | Marketing | 如需程式碼範例，請參閱「[`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" } ```