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. For more information, see Accessing product and customer data with the AWS Marketplace Commerce Analytics Service. These sections provide information about parameters, responses, and outputs related to datasets generated by the Commerce Analytics Service.

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.