AWS Service Catalog

(1)

AWS Service Catalog

Developer Guide

(2)

AWS Service Catalog: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What Is AWS Service Catalog?

AWS Service Catalog enables organizations to create and manage catalogs of products that are approved for use on AWS.

If you are new to AWS Service Catalog, see the following guides: AWS Service Catalog Administrator Guide and AWS Service Catalog User Guide.

Beneﬁts of Using the AWS Service Catalog API

The AWS Service Catalog API provides programmatic control over all end-user actions as an alternative to using the AWS Management Console. When you use the API, you can do the following:

• Write your own custom interfaces and apps

• Obtain ﬁne-grained control of end user product provisioning operations

• Integrate resource provisioning into your orchestration pipelines

• Access a central location that hosts your applications with their resources

Access AWS Service Catalog

To build applications using language-speciﬁc APIs, use the libraries, sample code, tutorials, and other resources for software developers. These libraries provide basic functions that automate tasks such as cryptographically signing your requests, retrying requests, and handling error responses, making it is easier for you to get started. To get started, open Tools for Amazon Web Services and locate the SDK of your choice under SDKs.

If you prefer to use a command line interface, you have the following options:

AWS Command Line Interface (CLI)

To get started, see the AWS Command Line Interface User Guide. For more information about the commands for AWS Service Catalog, see servicecatalog in the AWS CLI Command Reference.

AWS Tools for Windows PowerShell

To get started, see the AWS Tools for Windows PowerShell User Guide. For more information about the cmdlets for AWS Service Catalog, open the AWS Tools for PowerShell Cmdlet Reference and expand AWS Service Catalog.

Example Workﬂow

In this scenario, the administrator creates resources using AWS Service Catalog and an end user ﬁnds what products are available and provisions the product. This is an example workﬂow; this is not the only way to use the AWS Service Catalog API.

Administrator Tasks

• Create portfolios, product views, products, product versions, and constraints.

• Assign IAM users to products, which gives them access.

(5)

End User Tasks

1. The user calls SearchProducts (p. 211) with no arguments. This returns the list of products the user has access to, as well as a "SearchDomain" that can be used to scope the results.

2. The user continues to call SearchProducts (p. 211) with additional search ﬁlters until the desired product is found.

3. The user calls DescribeProductView (p. 101) to ﬁnd the list of provisioning artifacts (also known as versions) for this product. This determines what the user actually provisions.

4. The user calls ListLaunchPaths (p. 160) to ﬁnd the list of paths for this product, along with the constraints for each path. This determines what set of constraints is applied on the provisioned product.

5. After choosing a provisioning artifact and a path, the user calls

DescribeProvisioningParameters (p. 112). This returns the list of parameters the user must

provide before provisioning a product using the provisioning artifact and path, along with whatever additional usage instructions the administrator decided to provide.

6. The user calls ProvisionProduct (p. 201), specifying the product, provisioning artifact, path, and input parameters. The input parameters are a list of key-value pairs, where the keys are obtained using DescribeProvisioningParameters (p. 112) and the values are user-provided (for example, {ParameterKey:"dbpassword", ParameterValue:"mycoolpassword"}). This starts a workﬂow to create the speciﬁed AWS resources. It also creates a record detail that tracks the provisioning request, and a provisioned product object that represents the underlying AWS resources.

7. The user polls DescribeRecord (p. 116) to see when the status of the record detail changes from the IN_PROGRESS state to a completed state (either SUCCEEDED or ERROR).

8. When the record detail for the request is in a completed state, the user calls DescribeRecord (p. 116) once more. The outputs identiﬁes the created resources.

9. The user calls UpdateProvisionedProduct (p. 242) to update the underlying resources in place.

Depending on the speciﬁc updates requested, this operation can update with no interruption, with some interruption, or replace the provisioned product entirely.

10. Finally, the user calls TerminateProvisionedProduct (p. 224) to terminate the provisioned product.

(6)

AWS Service Catalog API Overview

The AWS Service Catalog API can be logically divided into the following categories.

Operations by category

• Product Discovery (p. 3)

• Provisioning Requests (p. 4)

• Provisioned Products (p. 4)

• Provisioned Product Plans (p. 5)

• Portfolios (p. 5)

• Principal Association (p. 6)

• Products (p. 6)

• Provisioning Artifacts (p. 7)

• Constraints (p. 7)

• Service Actions (p. 7)

• TagOptions (p. 8)

• AppRegistry (p. 8)

Product Discovery

Use these operations to discover or get information about products and the launch requirements for them. These operations do not create or modify resources.

SearchProducts (p. 211)

Lists all products to which the caller has access.

DescribeProduct (p. 94)

Get detailed information about a product.

DescribeProductView (p. 101)

Functionally identical to DescribeProduct, except that it takes the ID of a product view instead of the ID of a product.

ListLaunchPaths (p. 160)

Lists all of the ways the user has access to a speciﬁed product, referred to as paths to the product. A user must select a path in order to provision the product.

DescribeProvisioningParameters (p. 112)

Gets the parameters needed to provision a speciﬁed product, and provides additional metadata about what will happen when the product is provisioned.

Each ProvisioningArtifactParameter is something the user must specify in order to successfully provision the product (for example, the size of an EC2 instance). The

(7)

ConstraintSummary objects contain the list of allowable values and additional metadata about the ProvisioningArtifactParameter objects.

Provisioning Requests

Use these operations to request, update, or terminate provisioning for a product.

ProvisionProduct (p. 201)

Requests provisioning for a product. To provision a product is to launch the resources needed to bring that product online for actual use. For example, provisioning a product backed by an AWS CloudFormation template means launching an AWS CloudFormation stack and all its underlying resources.

UpdateProvisionedProduct (p. 242)

Updates the configuration of a provisioned product. For example, a product backed by AWS CloudFormation gets its underlying AWS CloudFormation stack updated. The requester must have sufficient access permissions to the specified ProvisionedProduct.

TerminateProvisionedProduct (p. 224)

Requests termination of a provisioned product. For example, for a product backed by AWS CloudFormation, this deletes the underlying AWS CloudFormation stack. The requester must have suﬃcient access permissions to the speciﬁed provisioned product.

Provisioned Products

Use these operations to get information about provisioned products. These operations do not create or modify resources.

ListRecordHistory (p. 185)

Lists all requests performed, even for terminated provisioned products.

DescribeRecord (p. 116)

Gets information about a request. Use this operation after the request operation to obtain current RecordDetail information.

SearchProvisionedProducts (p. 220)

Gets information about the provisioned products that meet speciﬁed criteria.

ScanProvisionedProducts (p. 208)

Lists the provisioned products that are not terminated.

DescribeProvisionedProduct (p. 103)

Gets information about a provisioned product.

ImportAsProvisionedProduct (p. 147)

Requests the import of a resource as a Service Catalog provisioned product that is associated to a Service Catalog product and provisioning artifact. Once imported, all supported Service Catalog governance actions are supported on the provisioned product.

UpdateProvisionedProductProperties (p. 247)

Requests updates to the properties of the speciﬁed provisioned product.

(8)

Provisioned Product Plans

Use these operations to manage your provisioned product plans. A plan includes the list of resources to create or modify when you execute the plan.

CreateProvisionedProductPlan (p. 50) Creates a plan.

DescribeProvisionedProductPlan (p. 106)

Gets information about the resource changes for a plan.

ExecuteProvisionedProductPlan (p. 137)

Provisions or modiﬁes a product based on a plan.

ListProvisionedProductPlans (p. 177)

Lists the plans for a provisioned product.

DeleteProvisionedProductPlan (p. 73) Deletes a plan.

Portfolios

Catalog administrators use these operations provide all necessary operations for portfolio management.

CreatePortfolio (p. 39) Creates a portfolio.

DeletePortfolio (p. 66) Deletes a portfolio.

DescribePortfolio (p. 85)

Gets detailed information about a portfolio.

DescribePortfolioShares (p. 88)

Returns a summary of each of the portfolio shares that were created for the speciﬁed portfolio.

ListPortfolios (p. 169)

Lists all portfolios in the catalog.

ListPortfoliosForProduct (p. 171)

Lists all portfolios that a product is associated with.

UpdatePortfolio (p. 231) Updates a portfolio.

UpdatePortfolioShare (p. 235) Updates a portfolio share.

CreatePortfolioShare (p. 42)

Shares a portfolio with an AWS account.

DeletePortfolioShare (p. 68) Stops sharing a portfolio.

(9)

AcceptPortfolioShare (p. 16)

Accepts an oﬀer to share a portfolio.

RejectPortfolioShare (p. 206)

Rejects an oﬀer to share a portfolio.

ListAcceptedPortfolioShares (p. 151)

Lists details of all portfolios for which sharing was accepted by this account.

ListPortfolioAccess (p. 166)

Lists the account IDs that have access to a portfolio.

Principal Association

Catalog administrators use these operations provide all necessary operations for principal association.

AssociatePrincipalWithPortfolio (p. 20)

Associates a principal ARN with a portfolio.

DisassociatePrincipalFromPortfolio (p. 128) Disassociates a principal ARN from a portfolio.

ListPrincipalsForPortfolio (p. 174)

Lists all principal ARNs associated with a portfolio.

Products

Catalog administrators use these operations provide all necessary operations for product management.

SearchProductsAsAdmin (p. 216)

Gets summary and status information for products.

DescribeProductAsAdmin (p. 97) Gets information about a product.

CreateProduct (p. 45) Creates a product.

CopyProduct (p. 32) Copies a product.

DescribeCopyProductStatus (p. 83)

Gets the status of a copy product operation.

UpdateProduct (p. 238) Updates a product.

DeleteProduct (p. 71) Deletes a product.

AssociateProductWithPortfolio (p. 22) Associates a product with a portfolio.

(10)

DisassociateProductFromPortfolio (p. 130) Disassociates a product from a portfolio.

Provisioning Artifacts

Catalog administrators use these operations manage provisioning artifacts (also known as product versions).

DescribeProvisioningArtifact (p. 109)

Gets information about a provisioning artifact.

CreateProvisioningArtifact (p. 55)

Creates a provisioning artifact for a product.

DeleteProvisioningArtifact (p. 75) Deletes a provisioning artifact.

ListProvisioningArtifacts (p. 180)

Lists all provisioning artifacts associated with a product.

UpdateProvisioningArtifact (p. 251) Updates a provisioning artifact.

Constraints

Catalog administrator use these operations manage constraints.

CreateConstraint (p. 35) Creates a constraint.

DeleteConstraint (p. 64) Deletes a constraint.

DescribeConstraint (p. 81)

Gets information about a constraint.

UpdateConstraint (p. 227) Updates a constraint.

ListConstraintsForPortfolio (p. 157)

Gets constraint information for the a portfolio and product.

Service Actions

Catalog administrators use these operations to manage service actions.

AssociateServiceActionWithProvisioningArtifact (p. 24)

Associates a self-service action with a provisioning artifact.

(11)

CreateServiceAction (p. 59) Creates a self-service action.

DeleteServiceAction (p. 77) Deletes a self-service action.

DescribeServiceAction (p. 119) Describes a self-service action.

DescribeServiceActionExecutionParameters (p. 121)

Finds the default parameters for a speciﬁc self-service action on a speciﬁc provisioned product and returns a map of the results to the user.

ExecuteProvisionedProductServiceAction (p. 140)

Executes a self-service action against a provisioned product.

UpdateServiceAction (p. 254) Updates a self-service action.

TagOptions

Catalog administrators use these operations to manage TagOptions.

CreateTagOption (p. 62) Creates a TagOption.

ListTagOptions (p. 199) Lists your TagOptions.

DescribeTagOption (p. 123) Describes a TagOption.

UpdateTagOption (p. 257) Updates a TagOption.

AssociateTagOptionWithResource (p. 26) Associates a TagOption with a resource.

DisassociateTagOptionFromResource (p. 134) Disassociates a TagOption from a resource.

ListResourcesForTagOption (p. 188) Lists the resources for a TagOption.

DeleteTagOption (p. 79) Deletes a TagOption.

AppRegistry

Serves as a repository for your applications, their resources, and the application metadata that you use in your enterprise.

(12)

AssociateAttributeGroup (p. 260)

Associates an attribute group with an application to augment the application's metadata with the group's attributes.

AssociateResource (p. 262)

Associates a resource with an application.

CreateApplication (p. 265)

Creates a new application that is the top-level node in a hierarchy of related cloud resource abstractions.

CreateAttributeGroup (p. 268)

Creates a new attribute group as a container for user-deﬁned attributes.

DeleteApplication (p. 271)

Deletes an application that is speciﬁed either by its application ID or name.

DeleteAttributeGroup (p. 273)

Deletes an attribute group, speciﬁed either by its attribute group ID or name.

DisassociateAttributeGroup (p. 275)

Disassociates an attribute group from an application to remove the extra attributes contained in the attribute group from the application's metadata.

DisassociateResource (p. 277)

Disassociates a resource from application.

GetApplication (p. 279)

Retrieves metadata information about one of your applications.

GetAssociatedResource (p. 282)

Gets the resource associated with the application.

GetAttributeGroup (p. 284)

Retrieves an attribute group, either by its name or its ID.

ListApplications (p. 287)

Lists all attribute groups that are associated with speciﬁed application.

ListAssociatedAttributeGroups (p. 289)

Lists all attribute groups that are associated with speciﬁed application.

ListAssociatedResources (p. 291)

Lists all resources that are associated with speciﬁed application.

ListAttributeGroups (p. 293)

Lists all attribute groups which you have access to.

ListTagsForResource (p. 295)

Lists all of the tags on the resource.

TagResource (p. 300)

Assigns one or more tags (key-value pairs) to the speciﬁed resource.

SyncResource (p. 297)

Syncs the resource with what is currently recorded in AppRegistry.

(13)

UntagResource (p. 302)

Removes tags from a resource.

UpdateApplication (p. 304)

Updates an existing application with new attributes.

UpdateAttributeGroup (p. 307)

Updates an existing attribute group with new details.

(14)

API Reference

The following actions and data types are supported:

• Actions (p. 11)

• Data Types (p. 309)

Actions

The following actions are supported by AWS Service Catalog:

• AcceptPortfolioShare (p. 16)

• AssociateBudgetWithResource (p. 18)

• AssociatePrincipalWithPortfolio (p. 20)

• AssociateProductWithPortfolio (p. 22)

• AssociateServiceActionWithProvisioningArtifact (p. 24)

• AssociateTagOptionWithResource (p. 26)

• BatchAssociateServiceActionWithProvisioningArtifact (p. 28)

• BatchDisassociateServiceActionFromProvisioningArtifact (p. 30)

• CopyProduct (p. 32)

• CreateConstraint (p. 35)

• CreatePortfolio (p. 39)

• CreatePortfolioShare (p. 42)

• CreateProduct (p. 45)

• CreateProvisionedProductPlan (p. 50)

• CreateProvisioningArtifact (p. 55)

• CreateServiceAction (p. 59)

• CreateTagOption (p. 62)

• DeleteConstraint (p. 64)

• DeletePortfolio (p. 66)

• DeletePortfolioShare (p. 68)

• DeleteProduct (p. 71)

• DeleteProvisionedProductPlan (p. 73)

• DeleteProvisioningArtifact (p. 75)

• DeleteServiceAction (p. 77)

• DeleteTagOption (p. 79)

• DescribeConstraint (p. 81)

• DescribeCopyProductStatus (p. 83)

• DescribePortfolio (p. 85)

• DescribePortfolioShares (p. 88)

• DescribePortfolioShareStatus (p. 91)

• DescribeProduct (p. 94)

• DescribeProductAsAdmin (p. 97)

(15)

• DescribeProductView (p. 101)

• DescribeProvisionedProduct (p. 103)

• DescribeProvisionedProductPlan (p. 106)

• DescribeProvisioningArtifact (p. 109)

• DescribeProvisioningParameters (p. 112)

• DescribeRecord (p. 116)

• DescribeServiceAction (p. 119)

• DescribeServiceActionExecutionParameters (p. 121)

• DescribeTagOption (p. 123)

• DisableAWSOrganizationsAccess (p. 125)

• DisassociateBudgetFromResource (p. 126)

• DisassociatePrincipalFromPortfolio (p. 128)

• DisassociateProductFromPortfolio (p. 130)

• DisassociateServiceActionFromProvisioningArtifact (p. 132)

• DisassociateTagOptionFromResource (p. 134)

• EnableAWSOrganizationsAccess (p. 136)

• ExecuteProvisionedProductPlan (p. 137)

• ExecuteProvisionedProductServiceAction (p. 140)

• GetAWSOrganizationsAccessStatus (p. 143)

• GetProvisionedProductOutputs (p. 144)

• ImportAsProvisionedProduct (p. 147)

• ListAcceptedPortfolioShares (p. 151)

• ListBudgetsForResource (p. 154)

• ListConstraintsForPortfolio (p. 157)

• ListLaunchPaths (p. 160)

• ListOrganizationPortfolioAccess (p. 163)

• ListPortfolioAccess (p. 166)

• ListPortfolios (p. 169)

• ListPortfoliosForProduct (p. 171)

• ListPrincipalsForPortfolio (p. 174)

• ListProvisionedProductPlans (p. 177)

• ListProvisioningArtifacts (p. 180)

• ListProvisioningArtifactsForServiceAction (p. 182)

• ListRecordHistory (p. 185)

• ListResourcesForTagOption (p. 188)

• ListServiceActions (p. 191)

• ListServiceActionsForProvisioningArtifact (p. 193)

• ListStackInstancesForProvisionedProduct (p. 196)

• ListTagOptions (p. 199)

• ProvisionProduct (p. 201)

• RejectPortfolioShare (p. 206)

• ScanProvisionedProducts (p. 208)

• SearchProducts (p. 211)

• SearchProductsAsAdmin (p. 216)

• SearchProvisionedProducts (p. 220)

• TerminateProvisionedProduct (p. 224)

(16)

• UpdateConstraint (p. 227)

• UpdatePortfolio (p. 231)

• UpdatePortfolioShare (p. 235)

• UpdateProduct (p. 238)

• UpdateProvisionedProduct (p. 242)

• UpdateProvisionedProductProperties (p. 247)

• UpdateProvisioningArtifact (p. 251)

• UpdateServiceAction (p. 254)

• UpdateTagOption (p. 257)

The following actions are supported by AWS Service Catalog AppRegistry:

• AssociateAttributeGroup (p. 260)

• AssociateResource (p. 262)

• CreateApplication (p. 265)

• CreateAttributeGroup (p. 268)

• DeleteApplication (p. 271)

• DeleteAttributeGroup (p. 273)

• DisassociateAttributeGroup (p. 275)

• DisassociateResource (p. 277)

• GetApplication (p. 279)

• GetAssociatedResource (p. 282)

• GetAttributeGroup (p. 284)

• ListApplications (p. 287)

• ListAssociatedAttributeGroups (p. 289)

• ListAssociatedResources (p. 291)

• ListAttributeGroups (p. 293)

• ListTagsForResource (p. 295)

• SyncResource (p. 297)

• TagResource (p. 300)

• UntagResource (p. 302)

• UpdateApplication (p. 304)

• UpdateAttributeGroup (p. 307)

AWS Service Catalog

The following actions are supported by AWS Service Catalog:

• AcceptPortfolioShare (p. 16)

• AssociateBudgetWithResource (p. 18)

• AssociatePrincipalWithPortfolio (p. 20)

• AssociateProductWithPortfolio (p. 22)

• AssociateServiceActionWithProvisioningArtifact (p. 24)

• AssociateTagOptionWithResource (p. 26)

• BatchAssociateServiceActionWithProvisioningArtifact (p. 28)

• BatchDisassociateServiceActionFromProvisioningArtifact (p. 30)

(17)

• CopyProduct (p. 32)

• CreateConstraint (p. 35)

• CreatePortfolio (p. 39)

• CreatePortfolioShare (p. 42)

• CreateProduct (p. 45)

• CreateProvisionedProductPlan (p. 50)

• CreateProvisioningArtifact (p. 55)

• CreateServiceAction (p. 59)

• CreateTagOption (p. 62)

• DeleteConstraint (p. 64)

• DeletePortfolio (p. 66)

• DeletePortfolioShare (p. 68)

• DeleteProduct (p. 71)

• DeleteProvisionedProductPlan (p. 73)

• DeleteProvisioningArtifact (p. 75)

• DeleteServiceAction (p. 77)

• DeleteTagOption (p. 79)

• DescribeConstraint (p. 81)

• DescribeCopyProductStatus (p. 83)

• DescribePortfolio (p. 85)

• DescribePortfolioShares (p. 88)

• DescribePortfolioShareStatus (p. 91)

• DescribeProduct (p. 94)

• DescribeProductAsAdmin (p. 97)

• DescribeProductView (p. 101)

• DescribeProvisionedProduct (p. 103)

• DescribeProvisionedProductPlan (p. 106)

• DescribeProvisioningArtifact (p. 109)

• DescribeProvisioningParameters (p. 112)

• DescribeRecord (p. 116)

• DescribeServiceAction (p. 119)

• DescribeServiceActionExecutionParameters (p. 121)

• DescribeTagOption (p. 123)

• DisableAWSOrganizationsAccess (p. 125)

• DisassociateBudgetFromResource (p. 126)

• DisassociatePrincipalFromPortfolio (p. 128)

• DisassociateProductFromPortfolio (p. 130)

• DisassociateServiceActionFromProvisioningArtifact (p. 132)

• DisassociateTagOptionFromResource (p. 134)

• EnableAWSOrganizationsAccess (p. 136)

• ExecuteProvisionedProductPlan (p. 137)

• ExecuteProvisionedProductServiceAction (p. 140)

• GetAWSOrganizationsAccessStatus (p. 143)

• GetProvisionedProductOutputs (p. 144)

• ImportAsProvisionedProduct (p. 147)

• ListAcceptedPortfolioShares (p. 151)

(18)

• ListBudgetsForResource (p. 154)

• ListConstraintsForPortfolio (p. 157)

• ListLaunchPaths (p. 160)

• ListOrganizationPortfolioAccess (p. 163)

• ListPortfolioAccess (p. 166)

• ListPortfolios (p. 169)

• ListPortfoliosForProduct (p. 171)

• ListPrincipalsForPortfolio (p. 174)

• ListProvisionedProductPlans (p. 177)

• ListProvisioningArtifacts (p. 180)

• ListProvisioningArtifactsForServiceAction (p. 182)

• ListRecordHistory (p. 185)

• ListResourcesForTagOption (p. 188)

• ListServiceActions (p. 191)

• ListServiceActionsForProvisioningArtifact (p. 193)

• ListStackInstancesForProvisionedProduct (p. 196)

• ListTagOptions (p. 199)

• ProvisionProduct (p. 201)

• RejectPortfolioShare (p. 206)

• ScanProvisionedProducts (p. 208)

• SearchProducts (p. 211)

• SearchProductsAsAdmin (p. 216)

• SearchProvisionedProducts (p. 220)

• TerminateProvisionedProduct (p. 224)

• UpdateConstraint (p. 227)

• UpdatePortfolio (p. 231)

• UpdatePortfolioShare (p. 235)

• UpdateProduct (p. 238)

• UpdateProvisionedProduct (p. 242)

• UpdateProvisionedProductProperties (p. 247)

• UpdateProvisioningArtifact (p. 251)

• UpdateServiceAction (p. 254)

• UpdateTagOption (p. 257)

(19)

AcceptPortfolioShare

Service: AWS Service Catalog

Accepts an oﬀer to share the speciﬁed portfolio.

Request Syntax

{

"AcceptLanguage": "string", "PortfolioId": "string", "PortfolioShareType": "string"

}

Request Parameters

The request accepts the following data in JSON format.

AcceptLanguage (p. 16) The language code.

• en - English (default)

• jp - Japanese

• zh - Chinese Type: String

Length Constraints: Maximum length of 100.

Required: No PortfolioId (p. 16)

The portfolio identiﬁer.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[a-zA-Z0-9_\-]*

Required: Yes

PortfolioShareType (p. 16)

The type of shared portfolios to accept. The default is to accept imported portfolios.

• AWS_ORGANIZATIONS - Accept portfolios shared by the management account of your organization.

• IMPORTED - Accept imported portfolios.

• AWS_SERVICECATALOG - Not supported. (Throws ResourceNotFoundException.) For example, aws servicecatalog accept-portfolio-share --portfolio-id

"port-2qwzkwxt3y5fk" --portfolio-share-type AWS_ORGANIZATIONS Type: String

Valid Values: IMPORTED | AWS_SERVICECATALOG | AWS_ORGANIZATIONS Required: No

(20)

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InvalidParametersException

One or more parameters provided to the operation are not valid.

HTTP Status Code: 400 LimitExceededException

The current limits of the service would have been exceeded by this operation. Decrease your resource use or increase your service limits and retry the operation.

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource was not found.

HTTP Status Code: 400

AssociateBudgetWithResource

Associates the speciﬁed budget with the speciﬁed resource.

Request Syntax

{ "BudgetName": "string", "ResourceId": "string"

}

Request Parameters

BudgetName (p. 18)

The name of the budget you want to associate.

Type: String

Required: Yes ResourceId (p. 18)

The resource identiﬁer. Either a portfolio-id or a product-id.

Type: String

Required: Yes

Response Elements

Errors

DuplicateResourceException

The speciﬁed resource is a duplicate.

HTTP Status Code: 400 InvalidParametersException

(22)

AssociatePrincipalWithPortfolio

Associates the speciﬁed principal ARN with the speciﬁed portfolio.

Request Syntax

{ "AcceptLanguage": "string", "PortfolioId": "string", "PrincipalARN": "string", "PrincipalType": "string"

}

Request Parameters

• jp - Japanese

Type: String

Required: Yes PrincipalARN (p. 20)

The ARN of the principal (IAM user, role, or group).

Type: String

Required: Yes PrincipalType (p. 20)

The principal type. The supported value is IAM.

Type: String Valid Values: IAM Required: Yes

(24)

Response Elements

Errors

AssociateProductWithPortfolio

Associates the speciﬁed product with the speciﬁed portfolio.

A delegated admin is authorized to invoke this command.

Request Syntax

{

"AcceptLanguage": "string", "PortfolioId": "string", "ProductId": "string",

"SourcePortfolioId": "string"

}

Request Parameters

• jp - Japanese

Type: String

Required: Yes ProductId (p. 22)

The product identiﬁer.

Type: String

Required: Yes SourcePortfolioId (p. 22)

The identiﬁer of the source portfolio.

Type: String

(26)

Required: No

Response Elements

Errors

AssociateServiceActionWithProvisioningArtifact

Associates a self-service action with a provisioning artifact.

Request Syntax

{ "AcceptLanguage": "string", "ProductId": "string",

"ProvisioningArtifactId": "string", "ServiceActionId": "string"

}

Request Parameters

• jp - Japanese

Required: No ProductId (p. 24)

The product identiﬁer. For example, prod-abcdzk7xy33qa.

Type: String

Required: Yes

ProvisioningArtifactId (p. 24)

The identiﬁer of the provisioning artifact. For example, pa-4abcdjnxjj6ne.

Type: String

Required: Yes ServiceActionId (p. 24)

The self-service action identiﬁer. For example, act-fs7abcd89wxyz.

Type: String

(28)

Required: Yes

Response Elements

Errors

AssociateTagOptionWithResource

Associate the speciﬁed TagOption with the speciﬁed portfolio or product.

Request Syntax

{ "ResourceId": "string", "TagOptionId": "string"

}

Request Parameters

ResourceId (p. 26)

The resource identiﬁer.

Type: String Required: Yes TagOptionId (p. 26)

The TagOption identiﬁer.

Type: String

Required: Yes

Response Elements

Errors

HTTP Status Code: 400 InvalidStateException

An attempt was made to modify a resource that is in a state that is not valid. Check your resources to ensure that they are in valid states before retrying the operation.

(30)

HTTP Status Code: 400 TagOptionNotMigratedException

An operation requiring TagOptions failed because the TagOptions migration process has not been performed for this account. Use the AWS Management Console to perform the migration process before retrying the operation.

BatchAssociateServiceActionWithProvisioningArtifact

Associates multiple self-service actions with provisioning artifacts.

Request Syntax

{

"AcceptLanguage": "string", "ServiceActionAssociations": [ {

"ProductId": "string",

} ] }

Request Parameters

• jp - Japanese

Required: No

ServiceActionAssociations (p. 28)

One or more associations, each consisting of the Action ID, the Product ID, and the Provisioning Artifact ID.

Type: Array of ServiceActionAssociation (p. 380) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes

Response Syntax

{ "FailedServiceActionAssociations": [ {

"ErrorCode": "string", "ErrorMessage": "string", "ProductId": "string",

} ]

(32)

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

FailedServiceActionAssociations (p. 28)

An object that contains a list of errors, along with information to help you identify the self-service action.

Type: Array of FailedServiceActionAssociation (p. 320) objects Array Members: Maximum number of 50 items.

Errors

BatchDisassociateServiceActionFromProvisioningArtifact

Disassociates a batch of self-service actions from the speciﬁed provisioning artifact.

Request Syntax

{

"AcceptLanguage": "string", "ServiceActionAssociations": [ {

"ProductId": "string",

} ] }

Request Parameters

• jp - Japanese

Required: No

ServiceActionAssociations (p. 30)

One or more associations, each consisting of the Action ID, the Product ID, and the Provisioning Artifact ID.

Type: Array of ServiceActionAssociation (p. 380) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes

Response Syntax

{ "FailedServiceActionAssociations": [ {

"ErrorCode": "string", "ErrorMessage": "string", "ProductId": "string",

} ]

(34)

}

Response Elements

FailedServiceActionAssociations (p. 30)

An object that contains a list of errors, along with information to help you identify the self-service action.

Type: Array of FailedServiceActionAssociation (p. 320) objects Array Members: Maximum number of 50 items.

Errors

CopyProduct

Copies the speciﬁed source product to the speciﬁed target product or a new product.

You can copy a product to the same account or another account. You can copy a product to the same Region or another Region. If you copy a product to another account, you must ﬁrst share the product in a portfolio using CreatePortfolioShare (p. 42).

This operation is performed asynchronously. To track the progress of the operation, use DescribeCopyProductStatus (p. 83).

Request Syntax

{ "AcceptLanguage": "string", "CopyOptions": [ "string" ], "IdempotencyToken": "string", "SourceProductArn": "string",

"SourceProvisioningArtifactIdentifiers": [ {

"string" : "string"

} ],

"TargetProductId": "string", "TargetProductName": "string"

}

Request Parameters

• jp - Japanese

Required: No CopyOptions (p. 32)

The copy options. If the value is CopyTags, the tags from the source product are copied to the target product.

Type: Array of strings Valid Values: CopyTags Required: No

IdempotencyToken (p. 32)

A unique identiﬁer that you provide to ensure idempotency. If multiple requests diﬀer only by the idempotency token, the same response is returned for each repeated request.

(36)

Type: String

Pattern: [a-zA-Z0-9][a-zA-Z0-9_-]*

Required: Yes

SourceProductArn (p. 32)

The Amazon Resource Name (ARN) of the source product.

Type: String

Pattern: arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]

{0,63}:[^/].{0,1023}

Required: Yes

SourceProvisioningArtifactIdentiﬁers (p. 32)

The identiﬁers of the provisioning artifacts (also known as versions) of the product to copy. By default, all provisioning artifacts are copied.

Type: Array of string to string maps Valid Keys: Id

Required: No TargetProductId (p. 32)

The identiﬁer of the target product. By default, a new product is created.

Type: String

Required: No

TargetProductName (p. 32)

A name for the target product. The default is the name of the source product.

Type: String

Required: No

Response Syntax

{ "CopyProductToken": "string"

}

Response Elements

(37)

CopyProductToken (p. 33)

The token to use to track the progress of the operation.

Type: String

Errors

CreateConstraint

Service: AWS Service Catalog Creates a constraint.

Request Syntax

{

"AcceptLanguage": "string", "Description": "string", "IdempotencyToken": "string", "Parameters": "string", "PortfolioId": "string", "ProductId": "string", "Type": "string"

}

Request Parameters

• jp - Japanese

Required: No Description (p. 35)

The description of the constraint.

Type: String

Required: No

Type: String

Required: Yes Parameters (p. 35)

The constraint parameters, in JSON format. The syntax depends on the constraint type as follows:

(39)

LAUNCH

You are required to specify either the RoleArn or the LocalRoleName but can't use both.

Specify the RoleArn property as follows:

{"RoleArn" : "arn:aws:iam::123456789012:role/LaunchRole"}

Specify the LocalRoleName property as follows:

{"LocalRoleName": "SCBasicLaunchRole"}

If you specify the LocalRoleName property, when an account uses the launch constraint, the IAM role with that name in the account will be used. This allows launch-role constraints to be account-agnostic so the administrator can create fewer resources per shared account.

NoteThe given role name must exist in the account used to create the launch constraint and the account of the user who launches a product with this launch constraint.

You cannot have both a LAUNCH and a STACKSET constraint.

You also cannot have more than one LAUNCH constraint on a product and portfolio.

NOTIFICATION

Specify the NotificationArns property as follows:

{"NotificationArns" : ["arn:aws:sns:us-east-1:123456789012:Topic"]}

RESOURCE_UPDATE

Specify the TagUpdatesOnProvisionedProduct property as follows:

{"Version":"2.0","Properties":

{"TagUpdateOnProvisionedProduct":"String"}}

The TagUpdatesOnProvisionedProduct property accepts a string value of ALLOWED or NOT_ALLOWED.

STACKSET

Specify the Parameters property as follows:

{"Version": "String", "Properties": {"AccountList": [ "String" ],

"RegionList": [ "String" ], "AdminRole": "String", "ExecutionRole":

"String"}}

You cannot have both a LAUNCH and a STACKSET constraint.

You also cannot have more than one STACKSET constraint on a product and portfolio.

Products with a STACKSET constraint will launch an AWS CloudFormation stack set.

TEMPLATE

Specify the Rules property. For more information, see Template Constraint Rules.

Type: String Required: Yes PortfolioId (p. 35)

(40)

Type: String

Required: Yes ProductId (p. 35)

The product identiﬁer.

Type: String

Required: Yes Type (p. 35)

The type of constraint.

• LAUNCH

• NOTIFICATION

• RESOURCE_UPDATE

• STACKSET

• TEMPLATE Type: String

Required: Yes

Response Syntax

{ "ConstraintDetail": { "ConstraintId": "string", "Description": "string", "Owner": "string", "PortfolioId": "string", "ProductId": "string", "Type": "string"

},

"ConstraintParameters": "string", "Status": "string"

}

Response Elements

ConstraintDetail (p. 37)

Information about the constraint.

(41)

Type: ConstraintDetail (p. 316) object ConstraintParameters (p. 37)

The constraint parameters.

Type: String Status (p. 37)

The status of the current request.

Type: String

Valid Values: AVAILABLE | CREATING | FAILED

Errors

CreatePortfolio

Service: AWS Service Catalog Creates a portfolio.

Request Syntax

{

"AcceptLanguage": "string", "Description": "string", "DisplayName": "string", "IdempotencyToken": "string", "ProviderName": "string", "Tags": [

{

"Key": "string", "Value": "string"

} ]}

Request Parameters

• jp - Japanese

The description of the portfolio.

Type: String

Required: No DisplayName (p. 39)

The name to use for display purposes.

Type: String

Required: Yes

(43)

Type: String

Required: Yes ProviderName (p. 39)

The name of the portfolio provider.

Type: String

Required: Yes Tags (p. 39)

One or more tags.

Type: Array of Tag (p. 386) objects

Array Members: Maximum number of 20 items.

Required: No

Response Syntax

{ "PortfolioDetail": { "ARN": "string", "CreatedTime": number, "Description": "string", "DisplayName": "string", "Id": "string",

"ProviderName": "string"

},

"Tags": [ {

} ] }

Response Elements

PortfolioDetail (p. 40)

Information about the portfolio.

(44)

Type: PortfolioDetail (p. 329) object Tags (p. 40)

Information about the tags associated with the portfolio.

Errors

CreatePortfolioShare

Shares the speciﬁed portfolio with the speciﬁed account or organization node. Shares to an organization node can only be created by the management account of an organization or by a delegated

administrator. You can share portfolios to an organization, an organizational unit, or a speciﬁc account.

Note that if a delegated admin is de-registered, they can no longer create portfolio shares.

AWSOrganizationsAccess must be enabled in order to create a portfolio share to an organization node.

You can't share a shared resource, including portfolios that contain a shared product.

If the portfolio share with the speciﬁed account or organization node already exists, this action will have no eﬀect and will not return an error. To update an existing share, you must use the UpdatePortfolioShare API instead.

Request Syntax

{ "AcceptLanguage": "string", "AccountId": "string", "OrganizationNode": { "Type": "string", "Value": "string"

},

"PortfolioId": "string", "ShareTagOptions": boolean }

Request Parameters

• jp - Japanese

Required: No AccountId (p. 42)

The AWS account ID. For example, 123456789012.

Type: String

Pattern: ^[0-9]{12}$

Required: No

OrganizationNode (p. 42)

The organization node to whom you are going to share. When you pass OrganizationNode, it creates PortfolioShare for all of the AWS accounts that are associated to the

(46)

OrganizationNode. The output returns a PortfolioShareToken, which enables the administrator to monitor the status of the PortfolioShare creation process.

Type: OrganizationNode (p. 326) object Required: No

PortfolioId (p. 42)

Type: String

Required: Yes ShareTagOptions (p. 42)

Enables or disables TagOptions sharing when creating the portfolio share. If this ﬂag is not provided, TagOptions sharing is disabled.

Type: Boolean Required: No

Response Syntax

{ "PortfolioShareToken": "string"

}

Response Elements

PortfolioShareToken (p. 43)

The portfolio shares a unique identiﬁer that only returns if the portfolio is shared to an organization node.

Type: String

Errors

(47)

InvalidStateException

An attempt was made to modify a resource that is in a state that is not valid. Check your resources to ensure that they are in valid states before retrying the operation.

OperationNotSupportedException The operation is not supported.

CreateProduct

Service: AWS Service Catalog Creates a product.

The user or role that performs this operation must have the cloudformation:GetTemplate IAM policy permission. This policy permission is required when using the ImportFromPhysicalId template source in the information data section.

Request Syntax

{ "AcceptLanguage": "string", "Description": "string", "Distributor": "string", "IdempotencyToken": "string", "Name": "string",

"Owner": "string", "ProductType": "string",

"ProvisioningArtifactParameters": { "Description": "string",

"DisableTemplateValidation": boolean, "Info": {

"string" : "string"

},

"Name": "string", "Type": "string"

},

"SupportDescription": "string", "SupportEmail": "string", "SupportUrl": "string", "Tags": [

{

} ]}

Request Parameters

• jp - Japanese

The description of the product.

(49)

Type: String

Required: No Distributor (p. 45)

The distributor of the product.

Type: String

Required: No

Type: String

Required: Yes Name (p. 45)

The name of the product.

Type: String

Required: Yes Owner (p. 45)

The owner of the product.

Type: String

Required: Yes ProductType (p. 45)

The type of product.

Type: String

Valid Values: CLOUD_FORMATION_TEMPLATE | MARKETPLACE Required: Yes

ProvisioningArtifactParameters (p. 45)

The conﬁguration of the provisioning artifact.

Type: ProvisioningArtifactProperties (p. 360) object

(50)

Required: Yes

SupportDescription (p. 45)

The support information about the product.

Type: String

Required: No SupportEmail (p. 45)

The contact email for product support.

Type: String

Required: No SupportUrl (p. 45)

The contact URL for product support.

^https?:\/\// / is the pattern used to validate SupportUrl.

Type: String

Required: No Tags (p. 45)

One or more tags.

Required: No

Response Syntax

{

"ProductViewDetail": { "CreatedTime": number, "ProductARN": "string", "ProductViewSummary": { "Distributor": "string", "HasDefaultPath": boolean, "Id": "string",

"Name": "string", "Owner": "string", "ProductId": "string", "ShortDescription": "string", "SupportDescription": "string", "SupportEmail": "string", "SupportUrl": "string", "Type": "string"

},

"Status": "string"

(51)

},

"ProvisioningArtifactDetail": { "Active": boolean,

"CreatedTime": number, "Description": "string", "Guidance": "string", "Id": "string", "Name": "string", "Type": "string"

},

"Tags": [ {

} ] }

Response Elements

ProductViewDetail (p. 47)

Information about the product view.

Type: ProductViewDetail (p. 335) object ProvisioningArtifactDetail (p. 47)

Information about the provisioning artifact.

Type: ProvisioningArtifactDetail (p. 354) object Tags (p. 47)

Information about the tags associated with the product.

Errors

(52)

AWS Service Catalog

AWS Service Catalog

Developer Guide

AWS Service Catalog: Developer Guide

Table of Contents

What Is AWS Service Catalog?

Beneﬁts of Using the AWS Service Catalog API

Access AWS Service Catalog

Example Workﬂow

AWS Service Catalog API Overview

Product Discovery

Provisioning Requests

Provisioned Products

Provisioned Product Plans

Portfolios

Principal Association

Products

Provisioning Artifacts

Constraints

Service Actions

TagOptions

AppRegistry

API Reference

Actions

AWS Service Catalog

AcceptPortfolioShare

Request Syntax

Request Parameters

Response Elements

Errors

See Also

AssociateBudgetWithResource

Request Syntax

Request Parameters

Response Elements

Errors

See Also

AssociatePrincipalWithPortfolio

Request Syntax

Request Parameters

Response Elements

Errors

See Also

AssociateProductWithPortfolio

Request Syntax

Request Parameters

Response Elements

Errors

See Also

AssociateServiceActionWithProvisioningArtifact

Request Syntax

Request Parameters

Response Elements

Errors

See Also

AssociateTagOptionWithResource

Request Syntax

Request Parameters

Response Elements

Errors

See Also

BatchAssociateServiceActionWithProvisioningArtifact

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

BatchDisassociateServiceActionFromProvisioningArtifact

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CopyProduct

Request Syntax

Request Parameters

Response Syntax

Response Elements