AWS Marketplace
Using AWS CLI to build and manage your organization’s Private Marketplace via APIs
With the launch of APIs for Private Marketplace, you now can programmatically manage your Private Marketplace in AWS Marketplace. Private Marketplace is a customized digital catalog that includes authorized software products available in AWS Marketplace. With Private Marketplace, administrators can choose from thousands of listings in AWS Marketplace to create a curated list of products your users can purchase. You can have different catalogs or entities for different parts of your business. You can now manage those entities using AWS Marketplace Discovery APIs.
Management tasks you can now perform using AWS Marketplace APIs include:
- Creating a Private Marketplace
- Updating branding on a Private Marketplace
- Listing all of your entities (an entity is a catalog, a Private Marketplace, or a procurement policy)
- Describing a specific entity
- Finding a product ID via AWS Marketplace Discovery API
- Adding or removing a specific product from an entity catalog
By using Private Marketplace APIs, you can integrate these operations into your ticketing system to streamline your procurement and provisioning processes. This minimizes turnaround time for your end users.
In this blog post, I show you how to use the AWS Command Line Interface (AWS CLI) to manage your Private Marketplace by making API calls.
Personas
- A Private Marketplace administrator is responsible for creation and maintenance of the Private Marketplace. This administrator also manages the approved list of software products for subscription across the organization.
- The AWS end user finds, buys, and uses software products in their individual accounts. They can subscribe and deploy software from Private Marketplace and request a product be added to the Private Marketplace.
Prerequisites
- The AWS CLI installed and configured with the account that you use to host your Private Marketplace. For more information, see Installing the AWS CLI and Configuring the AWS CLI in the AWS Command Line Interface User Guide.
- An AWS Software Development Key (SDK). In this blog post, I use AWS SDK for Python.
Solution Overview
In this solution, I will walk through the following functions:
- Setting up your Private Marketplace
- Create an AWS Identity and Access Management role
- Create a Private Marketplace (skip if you already have a Private Marketplace)
- Create a procurement policy (skip if you already have a Private Marketplace)
- Go live with and/or disable your Private Marketplace
- Create branding for your Private Marketplace (optional)
- Managing your Private Marketplace
- List all the ListEntities
- Describe a specific entity
- Check an entity’s settings
- Check an entity’s procurement policies
- Search for products using AWS Marketplace Discovery API
- Add a product to an entity
- List the changes made to the catalog
- Remove a product from the catalog entity
- Audit changes made to the catalog entity
Walkthrough
A. Setting up your Private Marketplace
Step 1: Create an AWS Identity and Access Management (IAM) role
To manage your Private Marketplace, you must first create an IAM role with Private Marketplace administrator privilege. Follow these steps to create the role.
- Log in to the IAM console with an IAM administrator user.
- Attach the AWSPrivateMarketplaceAdminFullAccess policy to users or groups. For more information, see Attaching a policy to an IAM group in the AWS Identity and Access Management User Guide.
Alternatively, you can also create a custom policy for your Private Marketplace administrators. Follow these steps to do so.
- On the IAM console, in the navigation pane, choose Policies.
- Choose Create policy.
- Choose the JSON
- Replace the template JSON with the following information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"aws-marketplace:ListEntities",
"aws-marketplace:DescribeEntity",
"aws-marketplace:ListChangeSets",
"aws-marketplace:DescribeChangeSet",
"aws-marketplace:CancelChangeSet"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "aws-marketplace:StartChangeSet",
"Resource": "*"
}
]
}
- Choose Review policy.
- Provide a name for the policy such as AWSPrivateMarketplaceAdminFullAccessPrivate.
- Choose Create Policy.
- Attach the AWSPrivateMarketplaceAdminFullAccess policy to users or groups.
Step 2: Create a Private Marketplace
You can skip this step if you have been using Private Marketplace in your account. To create a Private Marketplace, on the AWS CLI console run the following command.
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "CreateExperience", "Entity": {"Type": "Experience@1.0"}, "Details": "{\"Name\": \"CorpTestPrivateMarketplace\"}" } ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "75aqqll4m1vcco3XXXXXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/75aqqll4m1vcco3XXXXXXXX"
}
Take note of the ChangeSetID. You need it to find the experienceID. To find the experience ID, running the following command in AWS CLI.
aws marketplace-catalog describe-change-set --change-set-id 75aqqll4m1vcco3XXXXXXXX --catalog AWSMarketplace
You should get a successful response like this one:
{
"ChangeSetId": "75aqqll4m1vcco3XXXXXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/75aqqll4m1vcco3XXXXXXXX",
"ChangeSetName": "Submitted by AWS_Account_ID",
"StartTime": "2020-10-01T09:50:00Z",
"EndTime": "2020-10-01T09:50:37Z",
"Status": "SUCCEEDED",
"ChangeSet": [
{
"ChangeType": "CreateExperience",
"Entity": {
"Type": "Experience",
"Identifier": "exp-3vmeqjq6zXXXX@1"
},
"Details": "{\"Name\": \"CorpTestPrivateMarketplace\"}",
"ErrorDetailList": []
}
]
}
From that response, take note of the experience identifier experienceID. In the previous code, my experienceID is in between the quotation marks after “Identifier”:.
Step 3: Create a procurement policy
Using the experienceID from step A.2, create a procurement policy. A procurement policy is a portfolio of allowed or denied software. This step isn’t necessary if you already have a Private Marketplace. For the purposes of this blog post, I assume that you don’t have one. If you do, you can skip this step.
To create a procurement policy, run the following in AWS CLI, replacing my entity ID exp-3vmeqjq6XXXX with your entity ID:
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "CreateProcurementPolicy", "Entity": {"Identifier": "exp-3vmeqjq6zXXXX@1","Type": "Experience@1.0"}, "Details": "{\"Name\": \"CorpTestPrivateMarketplace\"}" } ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "cceu6fv868qwb9us2pk6fXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/cceu6fv868qwb9us2pk6fXXXX"
}
Step 4: Go live with your Private Marketplace
a. Going live
Before you can use your Private Marketplace, you must switch it to live mode. When your Private Marketplace is live, your end users are governed by the approved products in your Private Marketplace. This means they can only procure the allowed products in your Private Marketplace. To go live, update the experience to the Enabled status. Pay close attention to the revision of the experience identity (experienceId@revision-number). You can optionally increase it by 1 every time you update your entity to keep the audit trail.
To go live, run the following in AWS CLI, replacing my entity ID exp-3vmeqjq6XXXX with your entity ID:
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "UpdateExperience", "Entity": {"Identifier": "exp-3vmeqjq6zXXXX@2","Type": "Experience@1.0"}, "Details": "{\"Status\": \"Enabled\"}" } ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "3g8g92g868qwb9us2pk6fXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/3g8g92g 868qwb9us2pk6fXXXX"
}
Congratulations; your Private Marketplace is now live!
b. Disabling your Private Marketplace
If you no longer want your end users to be restricted only to your Private Marketplace and enable them to purchase anything available publicly in AWS Marketplace, you must disable your Private Marketplace. This enables users to find, buy, and deploy all products available in AWS Marketplace. To disable your Private Marketplace, run the following command in AWS CLI, replacing my entity ID exp-3vmeqjq6XXXX with your entity ID:
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "UpdateExperience", "Entity": {"Identifier": "exp-3vmeqjq6zXXXX@3","Type": "Experience@1.0"}, "Details": "{\"Status\": \"Disabled\"}" } ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "8dkr4j3rd9qwb9us2pk6fXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/8dkr4j3rd9qwb9us2pk6fXXXX "
}
Now your Private Marketplace is no longer live. To enable your Private Marketplace again, you must follow step 4A to switch your Private Marketplace back to live mode.
Step 5: Create branding for your Private Marketplace
Branding your Private Marketplace with your company name, colors, and logo lets your end users recognize they are in your organization’s authorized Private Marketplace. To create branding, run a following command similar to this one. Substitute the JSON values with your own colors, logo, and descriptors, and replace my entity ID exp-3vmeqjq6XXXX with your entity ID:
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "CreateBrandingSettings", "Entity": {"Identifier": " exp-3vmeqjq6zXXXX@4","Type": "Experience@1.0"}, "Details": "{\r\n \"Name\": \" CorpTestPMPBranding\",\r\n \"Description\": \"Branding for CorpTestPMP\",\r\n \"Configuration\":\r\n {\r\n \"Title\" : \"CorpTest\",\r\n \"Information\" : \"Welcome to CorpTest PMP.\",\r\n \"ThemeColor\" : \"#232f3e\",\r\n \"LogoUrl\" : \"https:\/\/trademarks.amazon.com\/media\/images\/available_at_amzn_tile.original.png\"\r\n }\r\n}" } ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "1lkk3l2j39qwb9us2pk6fXXXX",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ChangeSet/1lkk3l2j39qwb9us2pk6fXXXX"
}
B. Managing your Private Marketplace
Step 1: List all of the ListEntities
As mentioned in the introduction, you can now use AWS CLI to call APIs to manage your Private Marketplace. This includes enabling and disabling the Private Marketplace and adding and removing products.
An entity is a Private Marketplace catalog or portfolio. You might have different entities for different parts of your business. To manage an entity, you need the EntityID of the entity you want to work on. You can list all of the procurement policy entities by running the following command in AWS CLI:
aws marketplace-catalog list-entities --catalog AWSMarketplace --entity-type Experience
You should get a successful response similar to this one:
{
"EntitySummaryList": [
{
"Name": "CorpTestPrivateMarketplace",
"EntityType": "Experience",
"EntityId": "exp-3vmeqjq6XXXX",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-3vmeqjq6zrqb4",
"LastModifiedDate": "2020-10-01T10:31:56Z"
}
],
"NextToken": "rO0ABXVyABNbTGphdmEubGFuZy5PYmplY3Q7kM5YnxBzKWwCAAB4cAAAAAJzcgAOamF2YS5sYW5nLkxvbmc7i-"
}
Take note of the value of EntityID, which you need for catalog operations. The EntityID is what appears between the quotation marks after “EntityId”:. I noted from the AWS CLI response is exp-3vmeqjq6XXXX.
Step 2: Describe a specific entity
a. Checking an entity’s settings
A Private Marketplace’s entity settings including the procurement policy and branding settings, among others. To review a Private Marketplace’s entity settings, enter the following command into AWS CLI, replacing my entity ID exp-3vmeqjq6XXXX with your entity ID:
aws marketplace-catalog describe-entity --entity-id exp-3vmeqjq6XXXX --catalog AWSMarketplace
You should get a successful response similar to this one:
{
"EntityType": "Experience@1.0",
"EntityIdentifier": "exp-3vmeqjq6XXXX@5",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/Experience/exp-3vmeqjq6zrqb4",
"LastModifiedDate": "2020-10-01T10:31:56Z",
"Details": "{\"Name\":\"CorpTestPrivateMarketplace\",\"Status\":\"Disabled\",\"ProcurementPolicies\":[\"procpolicy-bd44tohelXXX\"],\"DiscoveryPolicies\":[],\"BrandingSettings\":[\"brandsettings-2j57t7nmkxlaq\"]}"
}
b. Checking an entity’s procurement policy
An entity’s procurement policy contains what software is approved or denied for users to procure. To review an entity’s procurement policy, enter the following command, replacing my policy ID procpolicy-bd44tohelXXX with your policy ID:
aws marketplace-catalog describe-entity --entity-id procpolicy-bd44tohelXXX --catalog AWSMarketplace
You should get a successful response similar to this one:
{
"EntityType": "ProcurementPolicy@1.0",
"EntityIdentifier": " procpolicy-bd44tohelXXX@16",
"EntityArn": "arn:aws:aws-marketplace:us-east-1: AWS_Account_ID:AWSMarketplace/ProcurementPolicy/procpolicy-bd44tohelXXX",
"LastModifiedDate": "2020-10-06T23:55:34Z",
"Details": "{\"Name\":\"CorpTestPrivateMarketplace\",\"Statements\":[{\"Effect\":\"Deny\",\"Resources\":[{\"Type\":\"Product\",\"Ids\":[\"c91cf0df-7622-4195-8974-b5678c5a9ae1\"]},{\"Type\":\"Product\",\"Ids\":[\"0625e4fd-88dd-4dd9-9e57-4a0461f97fb4\"]}]}],\"Configuration\":{\"PolicyResourceRequests\":\"Allow\"}}"
}
Pay attention to the revision version of EntityIdentifier (@revision_number). Every time you make changes to the catalog, you should increase the revision number.
Step 3: Search for products using AWS Marketplace Discovery API
To search for specific products in AWS Marketplace using AWS Marketplace Discovery API, you need an IntegrationID value on every request. This value is unique for each customer. If you’re not sure of your IntegrationID contact AWS. For more information on IntegrationID, review the AWS Marketplace Discovery API documentation, To search for products with AWS Marketplace Discovery API, run the following command with your IntegrationID and the product names as "search-text":
aws marketplace-discovery search-listings --request-context "IntegrationId" = "your-own-integrationid" --search-text "darktrace"
You should get a successful response similar to this one:
{
"ListingSummaries": [
{
"FulfillmentOptionTypes": [
{
"DisplayName": "SaaS",
"Value": "SAAS"
}
],
"Media": {
"LISTING_LOGO_THUMBNAIL": {
"Path": "/img/product/54750c60-c2bd-47ca-8e39-fe4f19c1c068/6338cd4a-c861-41a2-b87d-534a475b1df1.png",
"DefaultDomain": "https://d7umqicpi7263.cloudfront.net"
}
},
"Reviews": {
"AWS_MARKETPLACE": {
"Count": 0,
"Url": "https://aws.amazon.com/marketplace/reviews/reviews-list/B081S5HKR8",
"AverageCustomerRating": "0"
},
"G2": {
"Count": 22,
"Url": "https://www.g2.com/products/darktrace/reviews",
"AverageCustomerRating": "4"
}
},
"Badges": [],
"ProductAttributes": {
"BaseProductId": "54750c60-c2bd-47ca-8e39-fe4f19c1c068",
"Creator": {
"DisplayName": "Darktrace Ltd",
"Value": "c91cf0df-7622-4195-8974-b5678c5a9ae1"
}
},(truncated for visibility)
In these results, product IDs are represented as Values. You can select a product ID to add to your Private Marketplace entity. For example, to add Darktrace SaaS, I use product ID "c91cf0df-7622-4195-8974-b5678c5a9ae1" from Darktrace Ltd.
Step 4: Add a product to an entity
To add the Darktrace product from step B.3 to your Private Marketplace entity, run the following command. Use the latest revision number (experienceId@revision-number) obtained by repeating step B.2.a.
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "AllowProductProcurement", "Entity": {"Type": "Experience@1.0","Identifier": "exp-3vmeqjq6XXXX@5"}, "Details": "{\"Products\": [{\"Ids\":[\"c91cf0df-7622-4195-8974-b5678c5a9ae1\"],\"Note\": \"Darktrace AI\"}] }"} ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "69t7x0gXXXXX684pi01e75w",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/69t7x0gXXXXX684pi01e75w"
}
Optionally, you can add other products by repeating step B.2 to step B.4.
Step 5: List the changes made to the catalog
Before the next operation, make sure the changes have been recorded properly and successfully. To check all of the changes made to the catalog so far, run the following command.
aws marketplace-catalog list-change-sets --catalog AWSMarketplace
You should get a successful response similar to this one:
{
"ChangeSetSummaryList": [
{
"ChangeSetId": "7r420suwoudo2o709spx4xzcn",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/7r420suwoudo2o709spx4xzcn",
"ChangeSetName": "Submitted by 130071533271",
"StartTime": "2020-10-12T21:21:46Z",
"EndTime": "2020-10-12T21:22:40Z",
"Status": "SUCCEEDED",
"EntityIdList": [
"exp-3vmeqjq6XXXX"
]
},
{
"ChangeSetId": "2jut04ponhfybynkkn06ssvg2",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/2jut04ponhfybynkkn06ssvg2",
"ChangeSetName": "Submitted by 130071533271",
"StartTime": "2020-10-12T21:17:20Z",
"EndTime": "2020-10-12T21:18:13Z",
"Status": "SUCCEEDED",
"EntityIdList": [
"exp-3vmeqjq6XXXX"
]
},(truncated for visibility)
],
"NextToken":"rQ6AFaey033sAfQACAA5BV1NfQUNDT1VOVF9JRAAMMjczMTQxNjE2NDg2ABVhd3MtY3J5cHRvLXB1YmxpYy1rZXkAREF3bDdGTDYvXXXXXXXXXXXXXXXX"
}
At this point, to see all the products, you can repeat step B.2.b to describe the procurement policy entity.
Step 6: Remove a product from the catalog entity
There will be cases where you need to remove certain product from the catalog entity. If you no longer want a product approved in your Private Marketplace, you must remove it from the catalog entity. Keep in mind that when you remove a product, accounts currently subscribed it the product can continue to use it. However, new accounts will not be able to subscribe to the removed product.
To remove the product from a Private Marketplace entity, first run step B.2.a to ensure your ExperienceID has the latest revision number. Then run the following command and replace my ExperienceID with yours.
aws marketplace-catalog start-change-set --catalog AWSMarketplace --change-set '[ {"ChangeType": "DenyProductProcurement", "Entity": {"Type": "Experience@1.0","Identifier": "exp-3vmeqjq6XXXX@6"}, "Details": "{\"Products\": [{\"Ids\":[\" c91cf0df-7622-4195-8974-b5678c5a9ae1\]",\"Note\": \"Contact Procurement Team to purchase this product\"}] }"} ]'
You should get a successful response similar to this one:
{
"ChangeSetId": "40ohXXXXXXc5zhn4yyt9fjgn",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/40ohXXXXXXc5zhn4yyt9fjgn"
}
To list the changes made to the catalog again and verify that the product has been removed from the entity, repeat step B.5.
The response shows the addition and the removal of the same product under different ChangeSetIDs, like the following.
{
"ChangeSetId": "15itXXXXXXc5zhn4ydlkkj385",
"ChangeSetArn": "arn:aws:aws-marketplace:us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/15itXXXXXXc5zhn4ydlkkj385"
}
Step 7: Audit changes made to the catalog entity
Private Marketplace APIs support an audit trail that enable you to view who made which changes to the catalog entity. To view individual changes to a catalog entity, follow these steps.
- To list all of the changes, repeat step B.5.
- Take note of the ChangeSetId that you want to audit.
- Describe the target ChangeSetID by running the following command.
aws marketplace-catalog describe-change-set --change-set-id target-changesetid --catalog AWSMarketplace
You should get a successful response similar to this one:
{
"ChangeSetId": "88tkt589y5tla4v8ziex1t24w",
"ChangeSetArn": "arn:aws:aws-marketplace: us-east-1:AWS_Account_ID:AWSMarketplace/ChangeSet/88tkt589y5tla4v8ziex1t24w",
"ChangeSetName": "Submitted by 130071533271",
"StartTime": "2020-10-09T09:50:00Z",
"EndTime": "2020-10-09T09:50:37Z",
"Status": "SUCCEEDED",
"ChangeSet": [
{
"ChangeType": "CreateExperience",
"Entity": {
"Type": "Experience",
"Identifier": " exp-3vmeqjq6XXXX@1"
},
"Details": "{\"Name\": \"CorpTestPrivateMarketplace\"}",
"ErrorDetailList": []
}
]
}
Conclusion
In this post, I showed how to use the AWS CLI to manage your Private Marketplace via APIs. By using AWS Private Marketplace APIs instead of using the AWS Management Console, you can build your own integration with your internal ticketing or procurement systems. This reduces the efforts to meet your business needs to build and curate a Private Marketplace, as well as serving one-time requests to add and remove products from your Private Marketplace.
About the author
Nam Le, Senior Partner Solutions Architect, AWS Marketplace
Nam Le focuses on security and governance with close to 20 years of experience in consulting, sales, and engineering. He specializes in AWS Control Tower, AWS Service Catalog, AWS Marketplace, and AWS Data Exchange. As an AWS Marketplace solutions architect, he also works with AWS partners to build and deliver best-practices solutions to customers. Outside work, he enjoys biking, car building, travel photography, and spending time with family.