AddRevisions - AWS Data Exchange User Guide

AddRevisions

Important

Beginning July 22, 2021, new and existing providers have the ability to automatically publish revisions to data sets. All new products on AWS Data Exchange default to automatic revision publishing. If you have created existing products on AWS Data Exchange before July 22, 2021, you need to migrate them to automatic revision publishing.

For more information, see Migrating an existing product to automatic revision publishing.

Note

The following procedure is for existing providers who have not yet migrated their products to automatic revision publishing.

To publish new data set revisions to your AWS Data Exchange product, you need to create a change set of type AddRevisions. To do so, you can use the StartChangeSet API operation and specify the change type, the product id, the product type, and the details including the data set and revision Amazon Resource Names (ARNs).

You can update multiple products in a single AddRevisions change set. Each change is scoped to a single data set within a product. If your product has more than one data set and you need to update all of them, create a separate change for each data set.

Tutorial: Adding new data set revisions to a published data product

This tutorial walks you through detailed steps to publish new AWS Data Exchange data set revisions to an existing product. The tutorial has the following high-level steps.

Set up IAM permissions

Before you begin, you need AWS Identity and Access Management (IAM) permissions for using the AWS Marketplace Catalog API. These permissions are in addition to the permissions you need for using AWS Data Exchange.

  1. Navigate your browser to the IAM console and sign in using an AWS account that can manage IAM permissions.

  2. From the left navigation pane, choose Policies.

  3. Choose Create policy.

  4. Choose the JSON tab, and provide the following permissions. This provides full access to the AWS Marketplace Catalog API. You can restrict access as appropriate for your use case.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "aws-marketplace:CancelChangeSet", "aws-marketplace:ListChangeSets", "aws-marketplace:DescribeEntity", "aws-marketplace:StartChangeSet", "aws-marketplace:ListEntities", "aws-marketplace:DescribeChangeSet", "dataexchange:PublishDataSet" ], "Resource": "*" } ] }
  5. Choose Review policy.

  6. Provide a name for the policy (for example, CatalogAPIFullAccess), and then choose Create Policy.

  7. Using the IAM console, choose the users, groups, or roles that you want to attach the policy to.

Access the AWS Marketplace Catalog API

To access the AWS Marketplace Catalog API, use the following HTTP client endpoint.

catalog.marketplace.us-east-1.amazonaws.com

Get your product ID from the AWS Data Exchange console

Before you can use the AWS Marketplace Catalog API to publish new revisions, get your product ID from the AWS Data Exchange console. Navigate to the Product Dashboard, and then copy the product ID you would like to publish revisions for. You may also use the AWS Marketplace Catalog API to find your product ID, using the ListEntities action with the DataProduct@1.0 entity type.

Start a change request

To start a change request to add revisions to a data set in your test product

  1. Copy the entity ID that you get by following the instructions in Get your product ID from the AWS Data Exchange console.

  2. Make a StartChangeSet request with an AddRevisions change type. The details of the AddRevisions change object, in the request body, should contain the following:

    • DataSetArn – The data set to which you want to add revisions.

    • RevisionArns – The revisions that you want to publish to the data set in the product. For more information about the number of revisions that a single change can include, see AWS Data Exchange quotas.

Note

For more information about working with change sets in the AWS Marketplace Catalog API, see Working with change sets. For more information about working with the identifier for entities, see Identifier.

Example request

https://catalog.marketplace.us-east-1.amazonaws.com/StartChangeSet

Example request body

{ "Catalog": "AWSMarketplace", "ChangeSetName": "Adding revisions to my test Data Product", "ChangeSet": [ { "ChangeType": "AddRevisions", "Entity": { "Identifier": "entity-id@1", "Type": "DataProduct@1.0" }, "Details": "{\"DataSetArn\": \"data-set-arn\", \"RevisionArns\": [\"revision-arn\", \"revision-arn-2\"] }" } ] }

Example response

{ "ChangeSetId": "cs-bnEXAMPLE4mkz9oh", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:account-id:AWSMarketplace/ChangeSet/cs-bnEXAMPLE4mkz9oh" }

Check the status of your change set

After you use the StartChangeSet API operation to start the change request, you can use the DescribeChangeSet operation to check its status. Provide the change set ID returned in the StartChangeSet API response.

Example request

https://catalog.marketplace.us-east-1.amazonaws.com/DescribeChangeSet?catalog=AWSMarketplace&changeSetId=cs-bnEXAMPLE4mkz9oh

Example request body

{ "changeSetId":"cs-bnEXAMPLE4mkz9oh" }

Example response

{ "ChangeSetId": "cs-bnEXAMPLE4mkz9oh", "ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:account-id:AWSMarketplace/ChangeSet/cs-bnEXAMPLE4mkz9oh", "ChangeSetName": "Adding revisions to my test Data Product", "StartTime": "2018-09-20T19:45:03.115+0000", "EndTime": "2018-09-20T19:48:12.517+0000", "Status": "SUCCEEDED", "FailureDescription": null, "ChangeSet": [ { "ChangeType": "AddRevisions", "Entity": { "Type": "DataProduct@1.0", "Identifier": "entity-id@1" }, "ErrorList": [] } ] }

AddRevisions exceptions

The following exceptions can occur when you use the AWS Marketplace Catalog API with AWS Data Exchange:

REVISION_NOT_FOUND

This happens when the requested resource was not found. To resolve this issue, make sure that there's not a typo in the revision ARN and that your AWS account owns the resource, and try again.

REVISION_NOT_FINALIZED

Revisions must be finalized prior to being added to AWS Data Exchange products. To resolve this issue, ensure that the revisions with your specified ARNs are finalized, and try again.

DATA_SET_NOT_FOUND

This happens when the requested data set was not found. To resolve this issue, ensure that there's not a typo in the data set ARN and that your AWS account owns the data set, and try again.

INVALID_INPUT

The request couldn't be processed due to input that isn't valid. To resolve this issue, ensure that there's not a typo in the request and that the list of revisions has at least one and no more than five revisions.

DATA_SET_NOT_PUBLISHED

The requested resource has not been published in this product. To resolve this issue, ensure that there's not a typo in the ARNs for the data sets. You can also publish a new product that includes those data sets.

REVISION_DUPLICATE_PROVIDED

This happens when the same revision request occurs more than once. To resolve this issue, ensure that the revisions aren't duplicates, and try again.