/* * Copyright 2018-2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with * the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions * and limitations under the License. */ package com.amazonaws.services.marketplacemetering; import javax.annotation.Generated; import com.amazonaws.*; import com.amazonaws.regions.*; import com.amazonaws.services.marketplacemetering.model.*; /** * Interface for accessing AWSMarketplace Metering. *

* Note: Do not directly implement this interface, new methods are added to it regularly. Extend from * {@link com.amazonaws.services.marketplacemetering.AbstractAWSMarketplaceMetering} instead. *

*

* AWS Marketplace Metering Service *

* 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 *

* *

* Accepting New Customers *

* *

* Entitlement and Metering for Paid Container 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. *

*/ @Generated("com.amazonaws:aws-java-sdk-code-generator") public interface AWSMarketplaceMetering { /** * The region metadata service name for computing region endpoints. You can use this value to retrieve metadata * (such as supported regions) of the service. * * @see RegionUtils#getRegionsForService(String) */ String ENDPOINT_PREFIX = "metering.marketplace"; /** * Overrides the default endpoint for this client ("https://metering.marketplace.us-east-1.amazonaws.com"). Callers * can use this method to control which AWS region they want to work with. *

* Callers can pass in just the endpoint (ex: "metering.marketplace.us-east-1.amazonaws.com") or a full URL, * including the protocol (ex: "https://metering.marketplace.us-east-1.amazonaws.com"). If the protocol is not * specified here, the default protocol from this client's {@link ClientConfiguration} will be used, which by * default is HTTPS. *

* For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available * endpoints for all AWS services, see: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-region-selection.html#region-selection- * choose-endpoint *

* This method is not threadsafe. An endpoint should be configured when the client is created and before any * service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in * transit or retrying. * * @param endpoint * The endpoint (ex: "metering.marketplace.us-east-1.amazonaws.com") or a full URL, including the protocol * (ex: "https://metering.marketplace.us-east-1.amazonaws.com") of the region specific AWS endpoint this * client will communicate with. * @deprecated use {@link AwsClientBuilder#setEndpointConfiguration(AwsClientBuilder.EndpointConfiguration)} for * example: * {@code builder.setEndpointConfiguration(new EndpointConfiguration(endpoint, signingRegion));} */ @Deprecated void setEndpoint(String endpoint); /** * An alternative to {@link AWSMarketplaceMetering#setEndpoint(String)}, sets the regional endpoint for this * client's service calls. Callers can use this method to control which AWS region they want to work with. *

* By default, all service endpoints in all regions use the https protocol. To use http instead, specify it in the * {@link ClientConfiguration} supplied at construction. *

* This method is not threadsafe. A region should be configured when the client is created and before any service * requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit * or retrying. * * @param region * The region this client will communicate with. See {@link Region#getRegion(com.amazonaws.regions.Regions)} * for accessing a given region. Must not be null and must be a region where the service is available. * * @see Region#getRegion(com.amazonaws.regions.Regions) * @see Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration) * @see Region#isServiceSupported(String) * @deprecated use {@link AwsClientBuilder#setRegion(String)} */ @Deprecated void setRegion(Region region); /** *

* 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. *

* * * @param batchMeterUsageRequest * A 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 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 */ BatchMeterUsageResult batchMeterUsage(BatchMeterUsageRequest batchMeterUsageRequest); /** *

* API to emit metering records. For identical requests, the API is idempotent. It simply returns the metering * record ID. *

*

* MeterUsage 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). *

*

* 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. *

* * @param meterUsageRequest * @return Result of the MeterUsage 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 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 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 */ MeterUsageResult meterUsage(MeterUsageRequest meterUsageRequest); /** *

* 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 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 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 */ RegisterUsageResult registerUsage(RegisterUsageRequest registerUsageRequest); /** *

* ResolveCustomer 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. *

* *

* 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 ResolveCustomer, see * ResolveCustomer code example in the AWS Marketplace Seller Guide. *

* * * @param resolveCustomerRequest * Contains input to the 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 */ ResolveCustomerResult resolveCustomer(ResolveCustomerRequest resolveCustomerRequest); /** * Shuts down this client object, releasing any resources that might be held open. This is an optional method, and * callers are not expected to call it, but can if they want to explicitly release any open resources. Once a client * has been shutdown, it should not be used to make any more requests. */ void shutdown(); /** * Returns additional metadata for a previously executed successful request, typically used for debugging issues * where a service isn't acting as expected. This data isn't considered part of the result data returned by an * operation, so it's available through this separate, diagnostic interface. *

* 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 a request. * * @param request * The originally executed request. * * @return The response metadata for the specified request, or null if none is available. */ ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request); }