* Prerequisites: Follow the on-boarding guide: {URL OR SOMETHING} *
* Fill in your AWS access credentials in the provided credentials file * template, and be sure to move the file to the default location * (~/.aws/credentials) where the sample code will load the credentials from. *
* WARNING: To avoid accidental leakage of your credentials, DO NOT keep * the credentials file in your source directory. *
* http://aws.amazon.com/security-credentials */ public class MarketplaceCommerceAnalyticsSample { public static void main(String[] args) throws ParseException { /* * The ProfileCredentialsProvider will return your [default] * credential profile by reading from the credentials file located at * (~/.aws/credentials). */ AWSCredentials credentials = null; try { credentials = new ProfileCredentialsProvider().getCredentials(); } catch (Exception e) { throw new AmazonClientException("Cannot load the credentials from the credential profiles " + "file. Make sure that your credentials file is at the correct " + "location (~/.aws/credentials), and is in valid format.", e); } AWSMarketplaceCommerceAnalyticsClient client = new AWSMarketplaceCommerceAnalyticsClient(credentials); Region usEast1 = Region.getRegion(Regions.US_EAST_1); client.setRegion(usEast1); System.out.println("==============================================================="); System.out.println("Getting Started with AWS Marketplace Commerce Analytics Service"); System.out.println("===============================================================\n"); // Create a data set request with the desired parameters GenerateDataSetRequest request = new GenerateDataSetRequest(); request.setDataSetType("customer_subscriber_hourly_monthly_subscriptions"); request.setDataSetPublicationDate(convertIso8601StringToDateUtc("2014-06-09T00:00:00Z")); request.setRoleNameArn("arn:aws:iam::864545609859:role/MarketplaceCommerceAnalyticsRole"); request.setDestinationS3BucketName("awsmp-goldmine-seller"); request.setDestinationS3Prefix("java-sdk-test"); request.setSnsTopicArn("arn:aws:sns:us-west-2:864545609859:awsmp-goldmine-seller-topic"); System.out.println( String.format("Creating a request for data set %s for publication date %s.", request.getDataSetType(), request.getDataSetPublicationDate())); try { // Make the request to the service GenerateDataSetResult result = client.generateDataSet(request); // The Data Set Request ID is a unique identifier that you can use to correlate the // request with responses on your Amazon SNS topic System.out.println("Request successful, unique ID: " + result.getDataSetRequestId()); } catch (AmazonServiceException ase) { System.out.println("Caught an AmazonServiceException, which means your request made it " + "to the AWS Marketplace Commerce Analytics service, but was rejected with an " + "error response for some reason."); System.out.println("Error Message: " + ase.getMessage()); System.out.println("HTTP Status Code: " + ase.getStatusCode()); System.out.println("AWS Error Code: " + ase.getErrorCode()); System.out.println("Error Type: " + ase.getErrorType()); System.out.println("Request ID: " + ase.getRequestId()); } catch (AmazonClientException ace) { System.out.println("Caught an AmazonClientException, which means the client encountered " + "a serious internal problem while trying to communicate with the AWS Marketplace" + "Commerce Analytics service, such as not being able to access the " + "network."); System.out.println("Error Message: " + ace.getMessage()); } } private static Date convertIso8601StringToDateUtc(String dateIso8601) throws ParseException { TimeZone utcTimeZone = TimeZone.getTimeZone("UTC"); DateFormat utcDateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssX"); utcDateFormat.setTimeZone(utcTimeZone); return utcDateFormat.parse(dateIso8601); } } ``` You should expect results similar to this example. ``` =============================================================== Getting Started with AWS Marketplace Commerce Analytics Service =============================================================== Creating a request for data set customer_subscriber_hourly_monthly_subscriptions for publication date Sun Jun 08 17:00:00 PDT 2014. Request successful, unique ID: c59aff81-6875-11e5-a6d8-fd5dbcaa74ab ``` # Generating a dataset by using the AWS Marketplace Commerce Analytics Service After you enroll in the AWS Marketplace Commerce Analytics Service, you can access your usage, subscription, and billing reports through the AWS CLI and AWS SDK for Java. The data you request using the SDK tools is delivered to your AWS account as datasets. Most of the datasets correspond to the same data as the text-based reports available on the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/tour). For more information, see [Accessing product and customer data with the AWS Marketplace Commerce Analytics Service](commerce-analytics-service.md). These sections provide information about parameters, responses, and outputs related to datasets generated by the Commerce Analytics Service. **Topics** + [`GenerateDataSet` parameters](#generate-data-set-parameters) + [Responses](#responses) + [Outputs](#outputs) ## `GenerateDataSet` parameters The AWS Marketplace Commerce Analytics Service exposes one method, `GenerateDataSet`, which you can use to request datasets to be published to your Amazon S3 bucket. The following table lists the parameters for `GenerateDataSet`. **Dataset parameters** | **Field** | **Description** | | --- | --- | | Data Set Type | This dataset will be returned as the result of the request. | | Data Set Publication Date | The date a dataset was published. For daily datasets, provide a date with day-level granularity for the desired day. For monthly datasets, provide a date with month-level granularity for the desired month. The day value is ignored. | | Role Name ARN | The ARN of the role with an attached permissions policy that provides the service with access to your resources. | | Destination Amazon S3 Bucket Name | The name (the friendly name, not the ARN) of the destination Amazon S3 bucket. Your datasets are published to this location. | | Destination Amazon S3 Prefix | (Optional) The Amazon S3 prefix for the published dataset, similar to a directory path in standard file systems. For example, if given the bucket name `mybucket` and the prefix `myprefix/mydatasets`, the output file is published to `s3://amzn-s3-demo-bucket/myprefix/mydatasets/outputfile`. If the prefix directory structure doesn't exist, it's created. If no prefix is provided, the dataset is published to the Amazon S3 bucket root. | | SNS Topic ARN | The ARN for the Amazon SNS topic that is notified when the dataset has been published or if an error occurs. | ## Responses The AWS Marketplace Commerce Analytics Service returns two responses. The first is synchronous, which is returned immediately, and the second is asynchronous, which is returned using the Amazon SNS. The synchronous response is similar to this example. **Data set parameters** | **Field** | **Description** | | --- | --- | | Data Set Request ID | A unique identifier representing a specific request to the service. This identifier can be used to correlate a request with notifications on the Amazon SNS topic. | The asynchronous response is posted as a JSON-formatted document to your Amazon SNS topic and is similar to this example. **Dataset parameters** | **Field** | **Description** | | --- | --- | | Data Set S3 Location | The bucket name and key for the delivered dataset. | | Data Set Meta Data S3 Location | The bucket name and key for the delivered dataset metadata file. | | Data Set Request ID | A unique identifier representing a specific request to the service. This identifier can be used to correlate a request with notifications on the Amazon SNS topic. | | Success | "True" if the operation succeeded; "false" if not. | | Message | (Optional) If an error occurred (for example, "Success” is "false”), this message contains information about the failure. | **Example JSON-formatted asynchronous response** ``` { "dataSetS3Location":{ "bucketName":"demo-bucket", "key":"demo-prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.csv" }, "dataSetMetaDataS3Location":{ "bucketName":"demo-bucket", "key":"demo-prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.meta.json" }, "dataSetRequestId":"f65b7244-6862-11e5-80e2-c5127e17c023", "success":true } ``` ## Outputs After a successful request, the requested dataset is delivered to your Amazon S3 bucket as a .csv file. A JSON-formatted metadata file is published to the same location as the dataset file. The metadata file provides useful information about the dataset and original request parameters. The metadata file has the same name as the dataset file, but ends with the extension .meta.json. The following table lists the metadata fields in the .csv file. **Metadata fields** | **Field** | **Description** | | --- | --- | | Data Set Request ID | A unique identifier representing a specific request to the service. This identifier can be used to correlate a request with notifications on the Amazon SNS topic. | | Data Set Coverage Range | Defines the start date/time and end date/time for the data coverage range. These dates are in ISO 8601 format. | | Data Set Request Parameters | The original request parameters to the GenerateDataSet method. | | Data Set S3 Location | The bucket name and key for the delivered dataset. | | Data Set Meta Data S3 Location | The bucket name and key for the delivered dataset metadata file. | Following is an example of JSON-formatted metadata contents. ``` { "dataSetRequestId": "43d7137b-8a94-4042-a09d-c41e87f371c1", "dataSetCoverageRange": { "startDateTime": "2014-06-08T00:00:00.000Z", "endDateTime": "2014-06-08T23:59:59.000Z" }, "dataSetRequestParameters": { "sellerAccountId": "123412341234", "dataSetType": "customer_subscriber_hourly_monthly_subscriptions", "dataSetPublicationDate": "2014-06-09T00:00:00.000Z", "roleNameArn": "arn:aws:iam::123412341234:role/MarketplaceCommerceAnalyticsRole", "destinationS3BucketName": "demo-bucket", "destinationS3Prefix": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions", "snsTopicArn": "arn:aws:sns:us-west-2:123412341234:demo-topic" }, "dataSetS3Location": { "bucketName": "demo-bucket", "key": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.csv" }, "dataSetMetaDataS3Location": { "bucketName": "demo-bucket", "key": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.meta.json" } } ``` For a complete list of available datasets, including availability dates, refer to the [AWS SDK documentation](https://docs.aws.amazon.com/cli/latest/reference/marketplacecommerceanalytics/generate-data-set.html#options). # Troubleshooting the AWS Marketplace Commerce Analytics Service You can troubleshoot issues with the AWS Marketplace Commerce Analytics Service, which programmatically provides product and customers data from AWS Marketplace. You might need to troubleshoot the Commerce Analytics Service when you encounter errors or other configuration issues. The following sections guide you through the troubleshooting process, covering steps to diagnose and resolve common problems with the Commerce Analytics Service. **I can't access the service because of an allow list issue.** If you're not yet registered as a seller on the AWS Marketplace, visit [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management) to register. If you have already registered as a seller on AWS Marketplace, contact the [https://aws.amazon.com/marketplace/management/contact-us/](https://aws.amazon.com/marketplace/management/contact-us/) team. **I can't request datasets for a date in the past, even though the SDK documentation says it should be available for this date.** Even though datasets are listed as being available for certain dates in the past, we have data only since the time that you joined AWS Marketplace. If you believe that this is in error, contact the [https://aws.amazon.com/marketplace/management/contact-us/](https://aws.amazon.com/marketplace/management/contact-us/) team. **When I call the service, I receive the error message "Could not connect to the endpoint URL: https://marketplacecommerceanalytics.eu-central-1.amazonaws.com/”** The AWS Marketplace Commerce Analytics Service is available only in the US East (N. Virginia) Region. You must make all calls to the Commerce Analytics Service to the `us-east-1` endpoint. If you're using the AWS CLI, add the "`--region` flag to each call and specify the AWS Region as `us-east-1`, as shown in the following example. ``` aws marketplacecommerceanalytics generate-data-set \ --data-set-type "customer_subscriber_hourly_monthly_subscriptions" \ --data-set-publication-date "2016-04-21T00:00:00Z" \ --role-name-arn "arn:aws:iam::138136086619:role/MarketplaceCommerceAnalyticsRole" \ --destination-s3-bucket-name "marketplace-analytics-service" \ --destination-s3-prefix "test-prefix" \ --sns-topic-arn "arn:aws:sns:eu-central-1:138136086619:Marketplace_Analytics_Service_Notice" \ --region us-east-1 ``` **I want to use a different Amazon S3 bucket or Amazon SNS topic than the ones I selected when I went through the on-boarding process.** When enrolling in the AWS Marketplace Commerce Analytics Service, you specified an Amazon S3 bucket and Amazon SNS topic. The onboarding process configures your IAM permissions to allow the service access to only these specific resources. To use different resources, you need to modify your IAM policy: 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Choose ** Roles** on the left side of the IAM console. 1. Choose **MarketplaceCommerceAnalyticsRole**. 1. Expand the **Inline Roles** section, if not already expanded. 1. Locate the policy with a name that starts with *oneClick\$1MarketplaceCommerceAnalyticsRole* and choose **Edit Policy**. 1. In the policy document, locate the section that specifies actions related to the service that you want to modify. For example, to change your Amazon S3 bucket, locate the section that includes the actions that start with **s3:** and change their respective **Resource** selection to specify your new Amazon S3 bucket. For additional information about IAM policies, see the following guide: [https://docs.aws.amazon.com/IAM/latest/UserGuide/access\$1policies.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) **I get an `AccessDeniedException` error when I call the `GenerateDataSet` action** This can happen if your user doesn't have the permissions necessary to call `GenerateDataSet`. The following procedure outlines the steps needed to create an IAM policy with those permissions using the IAM console and add the permissions to your users, groups, or roles. **To use the JSON policy editor to create a policy** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane on the left, choose **Policies**. If this is your first time choosing **Policies**, the **Welcome to Managed Policies** page appears. Choose **Get Started**. 1. At the top of the page, choose **Create policy**. 1. In the **Policy editor** section, choose the **JSON** option. 1. Enter the following JSON policy document: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "marketplacecommerceanalytics:GenerateDataSet", "Resource": "*" } ] } ``` 1. Choose **Next**. **Note** You can switch between the **Visual** and **JSON** editor options anytime. However, if you make changes or choose **Next** in the **Visual** editor, IAM might restructure your policy to optimize it for the visual editor. For more information, see [Policy restructuring](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_policies.html#troubleshoot_viseditor-restructure) in the *IAM User Guide*. 1. On the **Review and create** page, enter a **Policy name** and a **Description** (optional) for the policy that you are creating. Review **Permissions defined in this policy** to see the permissions that are granted by your policy. 1. Choose **Create policy** to save your new policy. To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + Users managed in IAM through an identity provider: Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*. + IAM users: + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*. + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*. **My problem isn't listed here.** Contact the [https://aws.amazon.com/marketplace/management/contact-us/](https://aws.amazon.com/marketplace/management/contact-us/) team.