MeterUsage
API to emit metering records. For identical requests, the API is idempotent. It simply
returns the metering record ID. This is used for metering Flexible Consumption Pricing
(FCP) Amazon Machine Images (AMI) and Container products. MeterUsage
is
available in the following Regions:
- Commercial Regions
-
eu-north-1, me-south-1, ap-south-1, eu-west-3, ap-southeast-3, us-east-2, af-south-1, eu-west-1,me-central-1, eu-central-1, sa-east-1, ap-east-1, ap-south-2, us-east-1, ap-northeast-2, ap-northeast-3, eu-west-2, ap-southeast-4, eu-south-1, ap-northeast-1, us-west-2, us-west-1, ap-southeast-1, ap-southeast-2, il-central-1, ca-central-1, eu-south-2, eu-central-2
- GovCloud Regions
-
us-gov-east-1, us-gov-west-1
MeterUsage
is authenticated on the buyer's AWS account using
credentials from the Amazon EC2 instance, Amazon ECS task, or Amazon EKS pod.
MeterUsage
can optionally include multiple usage allocations, to provide
customers with usage data split into buckets by tags that you define (or allow the
customer to define).
Usage records are expected to be submitted as quickly as possible after the event that is being recorded, and are not accepted more than 6 hours after the event.
Request Syntax
{
"DryRun": boolean
,
"ProductCode": "string
",
"Timestamp": number
,
"UsageAllocations": [
{
"AllocatedUsageQuantity": number
,
"Tags": [
{
"Key": "string
",
"Value": "string
"
}
]
}
],
"UsageDimension": "string
",
"UsageQuantity": number
}
Request Parameters
The request accepts the following data in JSON format.
Note
In the following list, the required parameters are described first.
- ProductCode
-
Product code is used to uniquely identify a product in AWS Marketplace. The product code should be the same as the one used during the publishing of a new product.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 255.
Pattern:
^[-a-zA-Z0-9/=:_.@]*$
Required: Yes
- Timestamp
-
Timestamp, in UTC, for which the usage is being reported. Your application can meter usage for up to six hours in the past. Make sure the
timestamp
value is not before the start of the software usage.Type: Timestamp
Required: Yes
- UsageDimension
-
It will be one of the fcp dimension name provided during the publishing of the product.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 255.
Pattern:
[\s\S]+
Required: Yes
- DryRun
-
Checks whether you have the permissions required for the action, but does not make the request. If you have the permissions, the request returns
DryRunOperation
; otherwise, it returnsUnauthorizedException
. Defaults tofalse
if not specified.Type: Boolean
Required: No
- UsageAllocations
-
The set of
UsageAllocations
to submit.The sum of all
UsageAllocation
quantities must equal theUsageQuantity
of theMeterUsage
request, and eachUsageAllocation
must have a unique set of tags (include no tags).Type: Array of UsageAllocation objects
Array Members: Minimum number of 1 item. Maximum number of 2500 items.
Required: No
- UsageQuantity
-
Consumption value for the hour. Defaults to
0
if not specified.Type: Integer
Valid Range: Minimum value of 0. Maximum value of 2147483647.
Required: No
Response Syntax
{
"MeteringRecordId": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- MeteringRecordId
-
Metering record id.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors.
- CustomerNotEntitledException
-
Exception thrown when the customer does not have a valid subscription for the product.
HTTP Status Code: 400
- DuplicateRequestException
-
A metering record has already been emitted by the same EC2 instance, ECS task, or EKS pod for the given {
usageDimension
,timestamp
} with a differentusageQuantity
.HTTP Status Code: 400
- InternalServiceErrorException
-
An internal error has occurred. Retry your request. If the problem persists, post a message with details on the AWS forums.
HTTP Status Code: 500
- InvalidEndpointRegionException
-
The endpoint being called is in a AWS Region different from your EC2 instance, ECS task, or EKS pod. The Region of the Metering Service endpoint and the AWS Region of the resource must match.
HTTP Status Code: 400
- InvalidProductCodeException
-
The product code passed does not match the product code used for publishing the product.
HTTP Status Code: 400
- InvalidTagException
-
The tag is invalid, or the number of tags is greater than 5.
HTTP Status Code: 400
- InvalidUsageAllocationsException
-
Sum of allocated usage quantities is not equal to the usage quantity.
HTTP Status Code: 400
- InvalidUsageDimensionException
-
The usage dimension does not match one of the
UsageDimensions
associated with products.HTTP Status Code: 400
- ThrottlingException
-
The calls to the API are throttled.
HTTP Status Code: 400
- TimestampOutOfBoundsException
-
The
timestamp
value passed in theUsageRecord
is out of allowed range.For
BatchMeterUsage
, if any of the records are outside of the allowed range, the entire batch is not processed. You must remove invalid records and try again.HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: