Amazon Service Catalog API Overview
Benefits of Using the Service Catalog API
The Amazon Service Catalog API provides programmatic control over all end-user actions as an alternative to using the Amazon Web Services Management Console. When you use the API, you can do the following:
-
Write your own custom interfaces and apps
-
Obtain fine-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 Service Catalog
To build applications using language-specific 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 the Tools for Amazon Web Services
If you prefer to use a command line interface, you have the following options:
- Amazon Command Line Interface (CLI)
-
To get started, see the Amazon Command Line Interface User Guide. For more information about the commands for Service Catalog, see servicecatalog in the Amazon CLI Command Reference.
- Amazon Tools for Windows PowerShell
-
To get started, see the Amazon Tools for PowerShell User Guide. For more information about the cmdlets for Service Catalog, open the Amazon Tools for PowerShell Cmdlet Reference and expand Amazon Service Catalog.
The Amazon Service Catalog API can be logically divided into the following categories.
Topics
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
-
Lists all products to which the caller has access.
- DescribeProduct
-
Get detailed information about a product.
- DescribeProductView
-
Functionally identical to
DescribeProduct, except that it takes the ID of a product view instead of the ID of a product. - ListLaunchPaths
-
Lists all of the ways the user has access to a specified product, referred to as paths to the product. A user must select a path in order to provision the product.
- DescribeProvisioningParameters
-
Gets the parameters needed to provision a specified product, and provides additional metadata about what will happen when the product is provisioned.
Each
ProvisioningArtifactParameteris something the user must specify in order to successfully provision the product (for example, the size of an EC2 instance). TheConstraintSummaryobjects contain the list of allowable values and additional metadata about theProvisioningArtifactParameterobjects.
Provisioning Requests
Use these operations to request, update, or terminate provisioning for a product.
- ProvisionProduct
-
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 Amazon CloudFormation template means launching an Amazon CloudFormation stack and all its underlying resources.
- UpdateProvisionedProduct
-
Updates the configuration of a provisioned product. For example, a product backed by Amazon CloudFormation gets its underlying Amazon CloudFormation stack updated. The requester must have sufficient access permissions to the specified ProvisionedProduct.
- TerminateProvisionedProduct
-
Requests termination of a provisioned product. For example, for a product backed by Amazon CloudFormation, this deletes the underlying Amazon CloudFormation stack. The requester must have sufficient access permissions to the specified provisioned product.
Provisioned Products
Use these operations to get information about provisioned products. These operations do not create or modify resources.
- ListRecordHistory
-
Lists all requests performed, even for terminated provisioned products.
- DescribeRecord
-
Gets information about a request. Use this operation after the request operation to obtain current
RecordDetailinformation. - SearchProvisionedProducts
-
Gets information about the provisioned products that meet specified criteria.
- ScanProvisionedProducts
-
Lists the provisioned products that are not terminated.
- DescribeProvisionedProduct
-
Gets information about a provisioned product.
- ImportAsProvisionedProduct
-
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
-
Requests updates to the properties of the specified provisioned product.
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
Creates a plan.
- DescribeProvisionedProductPlan
Gets information about the resource changes for a plan.
- ExecuteProvisionedProductPlan
Provisions or modifies a product based on a plan.
- ListProvisionedProductPlans
Lists the plans for a provisioned product.
- DeleteProvisionedProductPlan
Deletes a plan.
Portfolios
Catalog administrators use these operations provide all necessary operations for portfolio management.
- CreatePortfolio
Creates a portfolio.
- DeletePortfolio
Deletes a portfolio.
- DescribePortfolio
Gets detailed information about a portfolio.
- DescribePortfolioShares
Returns a summary of each of the portfolio shares that were created for the specified portfolio.
- ListPortfolios
Lists all portfolios in the catalog.
- ListPortfoliosForProduct
Lists all portfolios that a product is associated with.
- UpdatePortfolio
Updates a portfolio.
- UpdatePortfolioShare
Updates a portfolio share.
- CreatePortfolioShare
Shares a portfolio with an Amazon account.
- DeletePortfolioShare
Stops sharing a portfolio.
- AcceptPortfolioShare
Accepts an offer to share a portfolio.
- RejectPortfolioShare
Rejects an offer to share a portfolio.
- ListAcceptedPortfolioShares
Lists details of all portfolios for which sharing was accepted by this account.
- ListPortfolioAccess
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
Associates a principal ARN with a portfolio.
- DisassociatePrincipalFromPortfolio
Disassociates a principal ARN from a portfolio.
- ListPrincipalsForPortfolio
Lists all principal ARNs associated with a portfolio.
Products
Catalog administrators use these operations provide all necessary operations for product management.
- SearchProductsAsAdmin
Gets summary and status information for products.
- DescribeProductAsAdmin
Gets information about a product.
- CreateProduct
Creates a product.
- CopyProduct
Copies a product.
- DescribeCopyProductStatus
Gets the status of a copy product operation.
- UpdateProduct
Updates a product.
- DeleteProduct
Deletes a product.
- AssociateProductWithPortfolio
Associates a product with a portfolio.
- DisassociateProductFromPortfolio
Disassociates a product from a portfolio.
Provisioning Artifacts
Catalog administrators use these operations to manage provisioning artifacts (also known as product versions).
- DescribeProvisioningArtifact
Gets information about a provisioning artifact.
- CreateProvisioningArtifact
Creates a provisioning artifact for a product.
- DeleteProvisioningArtifact
Deletes a provisioning artifact.
- ListProvisioningArtifacts
Lists all provisioning artifacts associated with a product.
- UpdateProvisioningArtifact
Updates a provisioning artifact.
Constraints
Catalog administrator use these operations manage constraints.
- CreateConstraint
Creates a constraint.
- DeleteConstraint
Deletes a constraint.
- DescribeConstraint
Gets information about a constraint.
- UpdateConstraint
Updates a constraint.
- ListConstraintsForPortfolio
Gets constraint information for the a portfolio and product.
Service Actions
Catalog administrators use these operations to manage service actions.
- AssociateServiceActionWithProvisioningArtifact
Associates a self-service action with a provisioning artifact.
- CreateServiceAction
Creates a self-service action.
- DeleteServiceAction
Deletes a self-service action.
- DescribeServiceAction
Describes a self-service action.
- DescribeServiceActionExecutionParameters
Finds the default parameters for a specific self-service action on a specific provisioned product and returns a map of the results to the user.
- ExecuteProvisionedProductServiceAction
Executes a self-service action against a provisioned product.
- UpdateServiceAction
Updates a self-service action.
TagOptions
Catalog administrators use these operations to manage TagOptions.
- CreateTagOption
Creates a TagOption.
- ListTagOptions
Lists your TagOptions.
- DescribeTagOption
Describes a TagOption.
- UpdateTagOption
Updates a TagOption.
- AssociateTagOptionWithResource
Associates a TagOption with a resource.
- DisassociateTagOptionFromResource
Disassociates a TagOption from a resource.
- ListResourcesForTagOption
Lists the resources for a TagOption.
- DeleteTagOption
Deletes a TagOption.
AppRegistry
Serves as a repository for your applications, their resources, and the application metadata that you use in your enterprise.
- AssociateAttributeGroup
Associates an attribute group with an application to augment the application's metadata with the group's attributes.
- AssociateResource
Associates a resource with an application.
- CreateApplication
Creates a new application that is the top-level node in a hierarchy of related cloud resource abstractions.
- CreateAttributeGroup
Creates a new attribute group as a container for user-defined attributes.
- DeleteApplication
Deletes an application that is specified either by its application ID or name.
- DeleteAttributeGroup
Deletes an attribute group, specified either by its attribute group ID or name.
- DisassociateAttributeGroup
Disassociates an attribute group from an application to remove the extra attributes contained in the attribute group from the application's metadata.
- DisassociateResource
Disassociates a resource from application.
- GetApplication
Retrieves metadata information about one of your applications.
- GetAssociatedResource
Gets the resource associated with the application.
- GetAttributeGroup
Retrieves an attribute group, either by its name or its ID.
- ListApplications
Lists all attribute groups that are associated with specified application.
- ListAssociatedAttributeGroups
Lists all attribute groups that are associated with specified application.
- ListAssociatedResources
Lists all resources that are associated with specified application.
- ListAttributeGroups
Lists all attribute groups of which you have access.
- ListAttributeGroupsForApplication
Lists the details of all attribute groups associated with a specific application.
- ListTagsForResource
Lists all of the tags on the resource.
- TagResource
Assigns one or more tags (key-value pairs) to the specified resource.
- SyncResource
Syncs the resource with what is currently recorded in AppRegistry.
- UntagResource
Removes tags from a resource.
- UpdateApplication
Updates an existing application with new attributes.
- UpdateAttributeGroup
Updates an existing attribute group with new details.
Example Workflow
In this scenario, the administrator creates resources using Amazon Service Catalog and an end user finds what products are available and provisions the product. This is an example workflow; this is not the only way to use the Amazon Service Catalog API.
Administrator Tasks
Create portfolios, product views, products, product versions, and constraints.
Assign IAM users to products, which gives them access.
End User Tasks
-
The user calls SearchProducts 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.
-
The user continues to call SearchProducts with additional search filters until the desired product is found.
-
The user calls DescribeProductView to find the list of provisioning artifacts (also known as versions) for this product. This determines what the user actually provisions.
-
The user calls ListLaunchPaths to find 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.
-
After choosing a provisioning artifact and a path, the user calls DescribeProvisioningParameters. 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.
-
The user calls ProvisionProduct, 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 and the values are user-provided (for example,
{ParameterKey:"dbpassword", ParameterValue:"mycoolpassword"}). This starts a workflow to create the specified Amazon resources. It also creates a record detail that tracks the provisioning request, and a provisioned product object that represents the underlying Amazon resources. -
The user polls DescribeRecord to see when the status of the record detail changes from the
IN_PROGRESSstate to a completed state (eitherSUCCEEDEDorERROR). -
When the record detail for the request is in a completed state, the user calls DescribeRecord once more. The outputs identifies the created resources.
-
The user calls UpdateProvisionedProduct to update the underlying resources in place. Depending on the specific updates requested, this operation can update with no interruption, with some interruption, or replace the provisioned product entirely.
-
Finally, the user calls TerminateProvisionedProduct to terminate the provisioned product.