*
* This reference provides descriptions of the low-level AWS Marketplace Metering Service API. *
** AWS Marketplace sellers can use this API to submit usage data for custom usage dimensions. *
** For information on the permissions you need to use this API, see AWS * Marketplace metering and entitlement API permissions in the AWS Marketplace Seller Guide. *
** Submitting Metering Records *
*
* MeterUsage - Submits the metering record for an AWS Marketplace product. MeterUsage is called
* from an EC2 instance or a container running on EKS or ECS.
*
* BatchMeterUsage - Submits the metering record for a set of customers. BatchMeterUsage is called
* from a software-as-a-service (SaaS) application.
*
* Accepting New Customers *
*
* ResolveCustomer - Called by a SaaS application during the registration process. When a buyer visits your
* website during the registration process, the buyer submits a Registration Token through the browser. The Registration
* Token is resolved through this API to obtain a CustomerIdentifier along with the
* CustomerAWSAccountId and ProductCode.
*
* Entitlement and Metering for Paid Container Products *
*
* Paid container software products sold through AWS Marketplace must integrate with the AWS Marketplace Metering
* Service and call the RegisterUsage operation for software entitlement and metering. Free and BYOL
* products for Amazon ECS or Amazon EKS aren't required to call RegisterUsage, but you can do so if you
* want to receive usage data in your seller reports. For more information on using the RegisterUsage
* operation, see Container-Based
* Products.
*
* BatchMeterUsage API calls are captured by AWS CloudTrail. You can use Cloudtrail to verify that the SaaS
* metering records that you sent are accurate by searching for records with the eventName of
* BatchMeterUsage. You can also use CloudTrail to audit records over time. For more information, see the
* AWS CloudTrail User
* Guide.
*
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @see DefaultAWSCredentialsProviderChain * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#defaultClient()} */ @Deprecated public AWSMarketplaceMeteringClient() { this(DefaultAWSCredentialsProviderChain.getInstance(), configFactory.getConfig()); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering. A credentials provider chain will * be used that searches for credentials in this order: *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param clientConfiguration * The client configuration options controlling how this client connects to AWSMarketplace Metering (ex: * proxy settings, retry counts, etc.). * * @see DefaultAWSCredentialsProviderChain * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withClientConfiguration(ClientConfiguration)} */ @Deprecated public AWSMarketplaceMeteringClient(ClientConfiguration clientConfiguration) { this(DefaultAWSCredentialsProviderChain.getInstance(), clientConfiguration); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified AWS account * credentials. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param awsCredentials * The AWS credentials (access key ID and secret key) to use when authenticating with AWS services. * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withCredentials(AWSCredentialsProvider)} for example: * {@code AWSMarketplaceMeteringClientBuilder.standard().withCredentials(new AWSStaticCredentialsProvider(awsCredentials)).build();} */ @Deprecated public AWSMarketplaceMeteringClient(AWSCredentials awsCredentials) { this(awsCredentials, configFactory.getConfig()); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified AWS account * credentials and client configuration options. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param awsCredentials * The AWS credentials (access key ID and secret key) to use when authenticating with AWS services. * @param clientConfiguration * The client configuration options controlling how this client connects to AWSMarketplace Metering (ex: * proxy settings, retry counts, etc.). * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withCredentials(AWSCredentialsProvider)} and * {@link AWSMarketplaceMeteringClientBuilder#withClientConfiguration(ClientConfiguration)} */ @Deprecated public AWSMarketplaceMeteringClient(AWSCredentials awsCredentials, ClientConfiguration clientConfiguration) { super(clientConfiguration); this.awsCredentialsProvider = new StaticCredentialsProvider(awsCredentials); this.advancedConfig = AdvancedConfig.EMPTY; init(); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified AWS account * credentials provider. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param awsCredentialsProvider * The AWS credentials provider which will provide credentials to authenticate requests with AWS services. * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withCredentials(AWSCredentialsProvider)} */ @Deprecated public AWSMarketplaceMeteringClient(AWSCredentialsProvider awsCredentialsProvider) { this(awsCredentialsProvider, configFactory.getConfig()); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified AWS account * credentials provider and client configuration options. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param awsCredentialsProvider * The AWS credentials provider which will provide credentials to authenticate requests with AWS services. * @param clientConfiguration * The client configuration options controlling how this client connects to AWSMarketplace Metering (ex: * proxy settings, retry counts, etc.). * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withCredentials(AWSCredentialsProvider)} and * {@link AWSMarketplaceMeteringClientBuilder#withClientConfiguration(ClientConfiguration)} */ @Deprecated public AWSMarketplaceMeteringClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration) { this(awsCredentialsProvider, clientConfiguration, null); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified AWS account * credentials provider, client configuration options, and request metric collector. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param awsCredentialsProvider * The AWS credentials provider which will provide credentials to authenticate requests with AWS services. * @param clientConfiguration * The client configuration options controlling how this client connects to AWSMarketplace Metering (ex: * proxy settings, retry counts, etc.). * @param requestMetricCollector * optional request metric collector * @deprecated use {@link AWSMarketplaceMeteringClientBuilder#withCredentials(AWSCredentialsProvider)} and * {@link AWSMarketplaceMeteringClientBuilder#withClientConfiguration(ClientConfiguration)} and * {@link AWSMarketplaceMeteringClientBuilder#withMetricsCollector(RequestMetricCollector)} */ @Deprecated public AWSMarketplaceMeteringClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration, RequestMetricCollector requestMetricCollector) { super(clientConfiguration, requestMetricCollector); this.awsCredentialsProvider = awsCredentialsProvider; this.advancedConfig = AdvancedConfig.EMPTY; init(); } public static AWSMarketplaceMeteringClientBuilder builder() { return AWSMarketplaceMeteringClientBuilder.standard(); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified parameters. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param clientParams * Object providing client parameters. */ AWSMarketplaceMeteringClient(AwsSyncClientParams clientParams) { this(clientParams, false); } /** * Constructs a new client to invoke service methods on AWSMarketplace Metering using the specified parameters. * *
* All service calls made using this new client object are blocking, and will not return until the service call * completes. * * @param clientParams * Object providing client parameters. */ AWSMarketplaceMeteringClient(AwsSyncClientParams clientParams, boolean endpointDiscoveryEnabled) { super(clientParams); this.awsCredentialsProvider = clientParams.getCredentialsProvider(); this.advancedConfig = clientParams.getAdvancedConfig(); init(); } private void init() { setServiceNameIntern(DEFAULT_SIGNING_NAME); setEndpointPrefix(ENDPOINT_PREFIX); // calling this.setEndPoint(...) will also modify the signer accordingly setEndpoint("https://metering.marketplace.us-east-1.amazonaws.com"); HandlerChainFactory chainFactory = new HandlerChainFactory(); requestHandler2s.addAll(chainFactory.newRequestHandlerChain("/com/amazonaws/services/marketplacemetering/request.handlers")); requestHandler2s.addAll(chainFactory.newRequestHandler2Chain("/com/amazonaws/services/marketplacemetering/request.handler2s")); requestHandler2s.addAll(chainFactory.getGlobalHandlers()); } /** *
* BatchMeterUsage is called from a SaaS application listed on AWS Marketplace to post metering records
* for a set of customers.
*
* For identical requests, the API is idempotent; requests can be retried with the same records or a subset of the * input records. *
*
* Every request to BatchMeterUsage is for one product. If you need to meter usage for multiple
* products, you must make multiple calls to BatchMeterUsage.
*
* 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. *
*
* BatchMeterUsage can process up to 25 UsageRecords at a time.
*
* A UsageRecord 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).
*
* BatchMeterUsage returns a list of UsageRecordResult objects, showing the result for
* each UsageRecord, as well as a list of UnprocessedRecords, indicating errors in the
* service side that you should retry.
*
* BatchMeterUsage requests must be less than 1MB in size.
*
* For an example of using BatchMeterUsage, see
* BatchMeterUsage code example in the AWS Marketplace Seller Guide.
*
BatchMeterUsageRequest contains UsageRecords, which indicate quantities of
* usage within your application.
* @return Result of the BatchMeterUsage operation returned by the service.
* @throws InternalServiceErrorException
* An internal error has occurred. Retry your request. If the problem persists, post a message with details
* on the AWS forums.
* @throws InvalidProductCodeException
* The product code passed does not match the product code used for publishing the product.
* @throws InvalidUsageDimensionException
* The usage dimension does not match one of the UsageDimensions associated with products.
* @throws InvalidTagException
* The tag is invalid, or the number of tags is greater than 5.
* @throws InvalidUsageAllocationsException
* The usage allocation objects are invalid, or the number of allocations is greater than 500 for a single
* usage record.
* @throws InvalidCustomerIdentifierException
* You have metered usage for a CustomerIdentifier that does not exist.
* @throws TimestampOutOfBoundsException
* The timestamp value passed in the UsageRecord is out of allowed range.
*
* For
* API to emit metering records. For identical requests, the API is idempotent. It simply returns the metering
* record ID.
*
*
*
* 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.
* 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.
* @throws ThrottlingException
* The calls to the API are throttled.
* @throws DisabledApiException
* The API is disabled in the Region.
* @sample AWSMarketplaceMetering.BatchMeterUsage
* @see AWS API Documentation
*/
@Override
public BatchMeterUsageResult batchMeterUsage(BatchMeterUsageRequest request) {
request = beforeClientExecution(request);
return executeBatchMeterUsage(request);
}
@SdkInternalApi
final BatchMeterUsageResult executeBatchMeterUsage(BatchMeterUsageRequest batchMeterUsageRequest) {
ExecutionContext executionContext = createExecutionContext(batchMeterUsageRequest);
AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics();
awsRequestMetrics.startEvent(Field.ClientExecuteTime);
RequestMeterUsage is authenticated on the buyer's AWS account using credentials from the EC2 instance, ECS
* task, or 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).
* UsageDimensions associated with products.
* @throws InvalidTagException
* The tag is invalid, or the number of tags is greater than 5.
* @throws InvalidUsageAllocationsException
* The usage allocation objects are invalid, or the number of allocations is greater than 500 for a single
* usage record.
* @throws 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.
* @throws TimestampOutOfBoundsException
* The timestamp value passed in the UsageRecord is out of allowed range.
* For
* Paid container software products sold through AWS Marketplace must integrate with the AWS Marketplace Metering
* Service and call the
* Entitlement:
* Metering:
*
* The API needs to called from the seller account id used to publish the SaaS application to successfully resolve
* the token.
*
* For an example of using
* Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic
* information for an executed request, you should use this method to retrieve it as soon as possible after
* executing the request.
*
* @param request
* The originally executed request
*
* @return The response metadata for the specified request, or null if none is available.
*/
public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request) {
return client.getResponseMetadataForRequest(request);
}
/**
* Normal invoke with authentication. Credentials are required and may be overriden at the request level.
**/
private 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.
* @throws 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 different usageQuantity.
* @throws ThrottlingException
* The calls to the API are throttled.
* @throws CustomerNotEntitledException
* Exception thrown when the customer does not have a valid subscription for the product.
* @sample AWSMarketplaceMetering.MeterUsage
* @see AWS
* API Documentation
*/
@Override
public MeterUsageResult meterUsage(MeterUsageRequest request) {
request = beforeClientExecution(request);
return executeMeterUsage(request);
}
@SdkInternalApi
final MeterUsageResult executeMeterUsage(MeterUsageRequest meterUsageRequest) {
ExecutionContext executionContext = createExecutionContext(meterUsageRequest);
AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics();
awsRequestMetrics.startEvent(Field.ClientExecuteTime);
RequestRegisterUsage operation for software entitlement and metering. Free and BYOL
* products for Amazon ECS or Amazon EKS aren't required to call RegisterUsage, but you may choose to
* do so if you would like to receive usage data in your seller reports. The sections below explain the behavior of
* RegisterUsage. RegisterUsage performs two primary functions: metering and entitlement.
*
*
*
* @param registerUsageRequest
* @return Result of the RegisterUsage operation returned by the service.
* @throws InvalidProductCodeException
* The product code passed does not match the product code used for publishing the product.
* @throws InvalidRegionException
* RegisterUsage allows you to verify that the customer running your paid software
* is subscribed to your product on AWS Marketplace, enabling you to guard against unauthorized use. Your container
* image that integrates with RegisterUsage is only required to guard against unauthorized use at
* container startup, as such a CustomerNotSubscribedException or
* PlatformNotSupportedException will only be thrown on the initial call to RegisterUsage.
* Subsequent calls from the same Amazon ECS task instance (e.g. task-id) or Amazon EKS pod will not throw a
* CustomerNotSubscribedException, even if the customer unsubscribes while the Amazon ECS task or
* Amazon EKS pod is still running.
* RegisterUsage meters software use per ECS task, per hour, or per pod for Amazon EKS
* with usage prorated to the second. A minimum of 1 minute of usage applies to tasks that are short lived. For
* example, if a customer has a 10 node Amazon ECS or Amazon EKS cluster and a service configured as a Daemon Set,
* then Amazon ECS or Amazon EKS will launch a task on all 10 cluster nodes and the customer will be charged: (10 *
* hourly_rate). Metering for software use is automatically handled by the AWS Marketplace Metering Control Plane --
* your software is not required to perform any metering specific actions, other than call
* RegisterUsage once for metering of software use to commence. The AWS Marketplace Metering Control
* Plane will also continue to bill customers for running ECS tasks and Amazon EKS pods, regardless of the customers
* subscription state, removing the need for your software to perform entitlement checks at runtime.
* RegisterUsage must be called in the same AWS Region the ECS task was launched in. This
* prevents a container from hardcoding a Region (e.g. withRegion(“us-east-1”) when calling
* RegisterUsage.
* @throws InvalidPublicKeyVersionException
* Public Key version is invalid.
* @throws PlatformNotSupportedException
* AWS Marketplace does not support metering usage from the underlying platform. Currently, Amazon ECS,
* Amazon EKS, and AWS Fargate are supported.
* @throws CustomerNotEntitledException
* Exception thrown when the customer does not have a valid subscription for the product.
* @throws ThrottlingException
* The calls to the API are throttled.
* @throws InternalServiceErrorException
* An internal error has occurred. Retry your request. If the problem persists, post a message with details
* on the AWS forums.
* @throws DisabledApiException
* The API is disabled in the Region.
* @sample AWSMarketplaceMetering.RegisterUsage
* @see AWS API Documentation
*/
@Override
public RegisterUsageResult registerUsage(RegisterUsageRequest request) {
request = beforeClientExecution(request);
return executeRegisterUsage(request);
}
@SdkInternalApi
final RegisterUsageResult executeRegisterUsage(RegisterUsageRequest registerUsageRequest) {
ExecutionContext executionContext = createExecutionContext(registerUsageRequest);
AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics();
awsRequestMetrics.startEvent(Field.ClientExecuteTime);
RequestResolveCustomer is called by a SaaS application during the registration process. When a buyer visits
* your website during the registration process, the buyer submits a registration token through their browser. The
* registration token is resolved through this API to obtain a CustomerIdentifier along with the
* CustomerAWSAccountId and ProductCode.
* ResolveCustomer, see
* ResolveCustomer code example in the AWS Marketplace Seller Guide.
* ResolveCustomer operation.
* @return Result of the ResolveCustomer operation returned by the service.
* @throws InvalidTokenException
* Registration token is invalid.
* @throws ExpiredTokenException
* The submitted registration token has expired. This can happen if the buyer's browser takes too long to
* redirect to your page, the buyer has resubmitted the registration token, or your application has held on
* to the registration token for too long. Your SaaS registration website should redeem this token as soon
* as it is submitted by the buyer's browser.
* @throws ThrottlingException
* The calls to the API are throttled.
* @throws InternalServiceErrorException
* An internal error has occurred. Retry your request. If the problem persists, post a message with details
* on the AWS forums.
* @throws DisabledApiException
* The API is disabled in the Region.
* @sample AWSMarketplaceMetering.ResolveCustomer
* @see AWS API Documentation
*/
@Override
public ResolveCustomerResult resolveCustomer(ResolveCustomerRequest request) {
request = beforeClientExecution(request);
return executeResolveCustomer(request);
}
@SdkInternalApi
final ResolveCustomerResult executeResolveCustomer(ResolveCustomerRequest resolveCustomerRequest) {
ExecutionContext executionContext = createExecutionContext(resolveCustomerRequest);
AWSRequestMetrics awsRequestMetrics = executionContext.getAwsRequestMetrics();
awsRequestMetrics.startEvent(Field.ClientExecuteTime);
Request