本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 設定 AMI 產品的自訂計量 AWS Marketplace Metering Service
**注意**
對於具有自訂計量定價的 AMI 型產品，您的軟體必須使用連接至 Amazon 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 搭配 Amazon Machine Image (AMI) 型、容器型和軟體即服務 (SaaS) 型產品。下列各節提供如何使用 AWS Marketplace Metering Service 設定自訂計量的詳細資訊。
AWS Marketplace Metering Service 可啟用數個新案例。例如，如果您的軟體監控主機，您可以針對每個受監控的主機收取費用。您可以根據主機大小有不同的價格，並按每小時監控的並行主機數量收費。同樣地，如果您的軟體允許組織中的許多使用者登入，您可以按使用者數量收費。每小時會向客戶收取佈建使用者總數的費用。
如需詳細資訊，請參閱 [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html)。
如需整合 AWS Marketplace Metering Service API for AMI 型產品與自訂計量定價的詳細資訊，請參閱*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)
## 要求
所有使用 Metering Service 的 AMI 型軟體都必須符合下列要求：
+ 您的軟體必須透過 AWS Marketplace Amazon Machine Image (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
您的軟體必須每小時呼叫 Metering Service，並記錄該小時的耗用量值。
當軟體啟動時，它應該記錄其啟動minute-of-the-hour。這稱為*開始分鐘*。開始分鐘的每個小時，您的軟體都必須判斷該小時的耗用量值，並呼叫計量服務。如需如何取得此值的資訊，請參閱[修改您的軟體以使用計量服務](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 Metering Service，類似於下列範例實作：
1. 使用執行個體描述檔來建立服務用戶端。這需要為 EC2 執行個體設定的角色。SDK 會自動重新整理角色登入資料。
1. 每小時讀取您的軟體組態和狀態，以判斷該小時的耗用值。這可能包括收集value-per-dimension。
1. 使用下列參數在 SDK 用戶端上呼叫 `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())。
## 失敗處理
您的產品必須將計量記錄傳送至公有網際網路端點服務，以便擷取用量並進行計費。由於客戶可以修改網路設定，以防止您的計量記錄交付，因此您的產品應該透過選擇失敗模式來考慮這一點。
**注意**
某些計量失敗可能是連線至 時的暫時性問題 AWS Marketplace Metering Service。 AWS Marketplace 強烈建議在指數退避的情況下實作重試最多 30 分鐘，以避免短期中斷或網路問題。
一般而言，軟體可能會開啟失敗 （提供警告訊息但維持完整功能） 或關閉失敗 （停用應用程式中的所有功能，直到重新建立連線為止）。您可以選擇失敗開啟、關閉或特定於您的應用程式。強烈建議您避免在不到兩小時的計量失敗後關閉。
作為部分開啟失敗的範例，您可以繼續允許存取軟體，但不允許買方修改軟體設定。或者，買方仍然可以存取軟體，但無法建立其他使用者。您的軟體負責定義和強制執行此失敗模式。提交 AMI 時，必須包含您軟體的失敗模式，之後無法變更。
## 限制
在設計和提交啟用 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 產品不支援啟動時的免費試用和年度訂閱。
+ **多執行個體或叢集型部署考量** – 有些軟體會部署為多執行個體部署的一部分。當您設計軟體時，請考慮如何測量耗用量以及在何處發出計量記錄。
## 程式碼範例
以下程式碼範例可協助您整合 AMI 產品與發佈和維護產品所需的 AWS Marketplace APIs。
### `MeterUsage` 使用用量分配標記 （選用）
下列程式碼範例適用於使用定價模型的 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`，請參閱《計量服務 API 參考》中的 [MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html)。 *AWS Marketplace *
### 回應範例
```
{ "MeteringRecordId": "string" }
```