/* * 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.services.marketplacemetering.model.*; /** * Interface for accessing AWSMarketplace Metering asynchronously. Each asynchronous method will return a Java Future * object representing the asynchronous operation; overloads which accept an {@code AsyncHandler} can be used to receive * notification when an asynchronous operation completes. *

* Note: Do not directly implement this interface, new methods are added to it regularly. Extend from * {@link com.amazonaws.services.marketplacemetering.AbstractAWSMarketplaceMeteringAsync} 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 AWSMarketplaceMeteringAsync extends AWSMarketplaceMetering { /** *

* 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 A Java Future containing the result of the BatchMeterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsync.BatchMeterUsage * @see AWS API Documentation */ java.util.concurrent.Future batchMeterUsageAsync(BatchMeterUsageRequest batchMeterUsageRequest); /** *

* 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. * @param asyncHandler * Asynchronous callback handler for events in the lifecycle of the request. Users can provide an * implementation of the callback methods in this interface to receive notification of successful or * unsuccessful completion of the operation. * @return A Java Future containing the result of the BatchMeterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsyncHandler.BatchMeterUsage * @see AWS API Documentation */ java.util.concurrent.Future batchMeterUsageAsync(BatchMeterUsageRequest batchMeterUsageRequest, com.amazonaws.handlers.AsyncHandler asyncHandler); /** *

* 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 A Java Future containing the result of the MeterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsync.MeterUsage * @see AWS * API Documentation */ java.util.concurrent.Future meterUsageAsync(MeterUsageRequest meterUsageRequest); /** *

* 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 * @param asyncHandler * Asynchronous callback handler for events in the lifecycle of the request. Users can provide an * implementation of the callback methods in this interface to receive notification of successful or * unsuccessful completion of the operation. * @return A Java Future containing the result of the MeterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsyncHandler.MeterUsage * @see AWS * API Documentation */ java.util.concurrent.Future meterUsageAsync(MeterUsageRequest meterUsageRequest, com.amazonaws.handlers.AsyncHandler asyncHandler); /** *

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

*
    *
  • *

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

    *
    • *
  • *

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

    *
    • *
* * @param registerUsageRequest * @return A Java Future containing the result of the RegisterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsync.RegisterUsage * @see AWS API Documentation */ java.util.concurrent.Future registerUsageAsync(RegisterUsageRequest registerUsageRequest); /** *

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

*
    *
  • *

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

    *
    • *
  • *

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

    *
    • *
* * @param registerUsageRequest * @param asyncHandler * Asynchronous callback handler for events in the lifecycle of the request. Users can provide an * implementation of the callback methods in this interface to receive notification of successful or * unsuccessful completion of the operation. * @return A Java Future containing the result of the RegisterUsage operation returned by the service. * @sample AWSMarketplaceMeteringAsyncHandler.RegisterUsage * @see AWS API Documentation */ java.util.concurrent.Future registerUsageAsync(RegisterUsageRequest registerUsageRequest, com.amazonaws.handlers.AsyncHandler asyncHandler); /** *

* 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 A Java Future containing the result of the ResolveCustomer operation returned by the service. * @sample AWSMarketplaceMeteringAsync.ResolveCustomer * @see AWS API Documentation */ java.util.concurrent.Future resolveCustomerAsync(ResolveCustomerRequest resolveCustomerRequest); /** *

* 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. * @param asyncHandler * Asynchronous callback handler for events in the lifecycle of the request. Users can provide an * implementation of the callback methods in this interface to receive notification of successful or * unsuccessful completion of the operation. * @return A Java Future containing the result of the ResolveCustomer operation returned by the service. * @sample AWSMarketplaceMeteringAsyncHandler.ResolveCustomer * @see AWS API Documentation */ java.util.concurrent.Future resolveCustomerAsync(ResolveCustomerRequest resolveCustomerRequest, com.amazonaws.handlers.AsyncHandler asyncHandler); }