Deployments - Create Or Update At Subscription Scope

Service:

Resource Management

API Version:

2021-04-01

Deploys resources at subscription scope.
You can provide the template and parameters directly in the request or link to JSON files.

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2021-04-01

URI Parameters

Name	In	Required	Type	Description
deploymentName	path	True	string	The name of the deployment. Regex pattern: ^[-\w\._\(\)]+$
subscriptionId	path	True	string	The Microsoft Azure subscription ID.
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
properties	True	DeploymentProperties	The deployment properties.
location		string	The location to store the deployment data.
tags		object	Deployment tags

Responses

Name	Type	Description
200 OK	DeploymentExtended	OK - Returns information about the deployment, including provisioning status.
201 Created	DeploymentExtended	Created - Returns information about the deployment, including provisioning status.
Other Status Codes	CloudError	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Create a deployment that will deploy a templateSpec with the given resourceId

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000001/providers/Microsoft.Resources/deployments/my-deployment?api-version=2021-04-01

{
  "location": "eastus",
  "properties": {
    "templateLink": {
      "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1"
    },
    "parameters": {},
    "mode": "Incremental"
  }
}

Go

package armresources_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armresources"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/4fd842fb73656039ec94ce367bcedee25a57bd18/specification/resources/resource-manager/Microsoft.Resources/stable/2021-04-01/examples/PutDeploymentSubscriptionTemplateSpecsWithId.json
func ExampleDeploymentsClient_BeginCreateOrUpdateAtSubscriptionScope() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armresources.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewDeploymentsClient().BeginCreateOrUpdateAtSubscriptionScope(ctx, "my-deployment", armresources.Deployment{
		Location: to.Ptr("eastus"),
		Properties: &armresources.DeploymentProperties{
			Mode:       to.Ptr(armresources.DeploymentModeIncremental),
			Parameters: map[string]any{},
			TemplateLink: &armresources.TemplateLink{
				ID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1"),
			},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.DeploymentExtended = armresources.DeploymentExtended{
	// 	Name: to.Ptr("my-deployment"),
	// 	Type: to.Ptr("Microsoft.Resources/deployments"),
	// 	ID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/providers/Microsoft.Resources/deployments/my-deployment"),
	// 	Location: to.Ptr("eastus"),
	// 	Properties: &armresources.DeploymentPropertiesExtended{
	// 		CorrelationID: to.Ptr("00000000-0000-0000-0000-000000000000"),
	// 		Dependencies: []*armresources.Dependency{
	// 		},
	// 		Duration: to.Ptr("PT1.2637681S"),
	// 		Mode: to.Ptr(armresources.DeploymentModeIncremental),
	// 		OutputResources: []*armresources.ResourceReference{
	// 		},
	// 		Parameters: map[string]any{
	// 		},
	// 		Providers: []*armresources.Provider{
	// 		},
	// 		ProvisioningState: to.Ptr(armresources.ProvisioningStateSucceeded),
	// 		TemplateHash: to.Ptr("0000000000000000000"),
	// 		TemplateLink: &armresources.TemplateLink{
	// 			ContentVersion: to.Ptr("1.0.0.0"),
	// 			ID: to.Ptr("/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1"),
	// 		},
	// 		Timestamp: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2020-06-05T01:51:58.628Z"); return t}()),
	// 	},
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { ResourceManagementClient } = require("@azure/arm-resources");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to You can provide the template and parameters directly in the request or link to JSON files.
 *
 * @summary You can provide the template and parameters directly in the request or link to JSON files.
 * x-ms-original-file: specification/resources/resource-manager/Microsoft.Resources/stable/2021-04-01/examples/PutDeploymentSubscriptionTemplateSpecsWithId.json
 */
async function createADeploymentThatWillDeployATemplateSpecWithTheGivenResourceId() {
  const subscriptionId =
    process.env["RESOURCES_SUBSCRIPTION_ID"] || "00000000-0000-0000-0000-000000000001";
  const deploymentName = "my-deployment";
  const parameters = {
    location: "eastus",
    properties: {
      mode: "Incremental",
      parameters: {},
      templateLink: {
        id: "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1",
      },
    },
  };
  const credential = new DefaultAzureCredential();
  const client = new ResourceManagementClient(credential, subscriptionId);
  const result = await client.deployments.beginCreateOrUpdateAtSubscriptionScopeAndWait(
    deploymentName,
    parameters
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:

200

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000001/providers/Microsoft.Resources/deployments/my-deployment",
  "name": "my-deployment",
  "type": "Microsoft.Resources/deployments",
  "location": "eastus",
  "properties": {
    "templateLink": {
      "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1",
      "contentVersion": "1.0.0.0"
    },
    "templateHash": "0000000000000000000",
    "parameters": {},
    "mode": "Incremental",
    "provisioningState": "Succeeded",
    "timestamp": "2020-06-05T01:51:58.6288067Z",
    "duration": "PT1.2637681S",
    "correlationId": "00000000-0000-0000-0000-000000000000",
    "providers": [],
    "dependencies": [],
    "outputResources": []
  }
}

Status code:

201

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000001/providers/Microsoft.Resources/deployments/my-deployment",
  "name": "my-deployment",
  "type": "Microsoft.Resources/deployments",
  "location": "eastus",
  "properties": {
    "templateLink": {
      "id": "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/my-resource-group/providers/Microsoft.Resources/TemplateSpecs/TemplateSpec-Name/versions/v1",
      "contentVersion": "1.0.0.0"
    },
    "templateHash": "0000000000000000000",
    "parameters": {},
    "mode": "Incremental",
    "provisioningState": "Accepted",
    "timestamp": "2020-06-05T01:51:58.6288067Z",
    "duration": "PT1.2637681S",
    "correlationId": "00000000-0000-0000-0000-000000000000",
    "providers": [],
    "dependencies": []
  }
}

Definitions

Name	Description
Alias	The alias type.
AliasPath	The type of the paths for alias.
AliasPathAttributes	The attributes of the token that the alias path is referring to.
AliasPathMetadata
AliasPathTokenType	The type of the token that the alias path is referring to.
AliasPattern	The type of the pattern for an alias path.
AliasPatternType	The type of alias pattern
AliasType	The type of the alias.
ApiProfile
BasicDependency	Deployment dependency information.
CloudError	An error response for a resource management request.
DebugSetting	The debug setting.
Dependency	Deployment dependency information.
Deployment	Deployment operation parameters.
DeploymentExtended	Deployment information.
DeploymentMode	The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.
DeploymentProperties	Deployment properties.
DeploymentPropertiesExtended	Deployment properties with additional details.
ErrorAdditionalInfo	The resource management error additional info.
ErrorResponse	Error Response
ExpressionEvaluationOptions	Specifies whether template expressions are evaluated within the scope of the parent template or nested template.
ExpressionEvaluationOptionsScopeType	The scope to be used for evaluation of parameters, variables and functions in a nested template.
OnErrorDeployment	Deployment on error behavior.
OnErrorDeploymentExtended	Deployment on error behavior with additional details.
OnErrorDeploymentType	The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.
ParametersLink	Entity representing the reference to the deployment parameters.
Provider	Resource provider information.
ProviderAuthorizationConsentState	The provider authorization consent state.
ProviderExtendedLocation	The provider extended location.
ProviderResourceType	Resource type managed by the resource provider.
ProvisioningState	Denotes the state of provisioning.
ResourceReference	The resource Id model.
TemplateLink	Entity representing the reference to the template.
ZoneMapping

Alias

The alias type.

Name	Type	Description
defaultMetadata	AliasPathMetadata	The default alias path metadata. Applies to the default path and to any alias path that doesn't have metadata
defaultPath	string	The default path for an alias.
defaultPattern	AliasPattern	The default pattern for an alias.
name	string	The alias name.
paths	AliasPath[]	The paths for an alias.
type	AliasType	The type of the alias.

AliasPath

The type of the paths for alias.

Name	Type	Description
apiVersions	string[]	The API versions.
metadata	AliasPathMetadata	The metadata of the alias path. If missing, fall back to the default metadata of the alias.
path	string	The path of an alias.
pattern	AliasPattern	The pattern for an alias path.

AliasPathAttributes

The attributes of the token that the alias path is referring to.

Name	Type	Description
Modifiable	string	The token that the alias path is referring to is modifiable by policies with 'modify' effect.
None	string	The token that the alias path is referring to has no attributes.

AliasPathMetadata

Name	Type	Description
attributes	AliasPathAttributes	The attributes of the token that the alias path is referring to.
type	AliasPathTokenType	The type of the token that the alias path is referring to.

AliasPathTokenType

The type of the token that the alias path is referring to.

Name	Type	Description
Any	string	The token type can be anything.
Array	string	The token type is array.
Boolean	string	The token type is boolean.
Integer	string	The token type is integer.
NotSpecified	string	The token type is not specified.
Number	string	The token type is number.
Object	string	The token type is object.
String	string	The token type is string.

AliasPattern

The type of the pattern for an alias path.

Name	Type	Description
phrase	string	The alias pattern phrase.
type	AliasPatternType	The type of alias pattern
variable	string	The alias pattern variable.

AliasPatternType

The type of alias pattern

Name	Type	Description
Extract	string	Extract is the only allowed value.
NotSpecified	string	NotSpecified is not allowed.

AliasType

The type of the alias.

Name	Type	Description
Mask	string	Alias value is secret.
NotSpecified	string	Alias type is unknown (same as not providing alias type).
PlainText	string	Alias value is not secret.

ApiProfile

Name	Type	Description
apiVersion	string	The API version.
profileVersion	string	The profile version.

BasicDependency

Deployment dependency information.

Name	Type	Description
id	string	The ID of the dependency.
resourceName	string	The dependency resource name.
resourceType	string	The dependency resource type.

CloudError

An error response for a resource management request.

Name	Type	Description
error	ErrorResponse	Error Response Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.)

DebugSetting

The debug setting.

Name	Type	Description
detailLevel	string	Specifies the type of information to log for debugging. The permitted values are none, requestContent, responseContent, or both requestContent and responseContent separated by a comma. The default is none. When setting this value, carefully consider the type of information you are passing in during deployment. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations.

Dependency

Deployment dependency information.

Name	Type	Description
dependsOn	BasicDependency[]	The list of dependencies.
id	string	The ID of the dependency.
resourceName	string	The dependency resource name.
resourceType	string	The dependency resource type.

Deployment

Deployment operation parameters.

Name	Type	Description
location	string	The location to store the deployment data.
properties	DeploymentProperties	The deployment properties.
tags	object	Deployment tags

DeploymentExtended

Deployment information.

Name	Type	Description
id	string	The ID of the deployment.
location	string	the location of the deployment.
name	string	The name of the deployment.
properties	DeploymentPropertiesExtended	Deployment properties.
tags	object	Deployment tags
type	string	The type of the deployment.

DeploymentMode

The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.

Name	Type	Description
Complete	string
Incremental	string

DeploymentProperties

Deployment properties.

Name	Type	Description
debugSetting	DebugSetting	The debug setting of the deployment.
expressionEvaluationOptions	ExpressionEvaluationOptions	Specifies whether template expressions are evaluated within the scope of the parent template or nested template. Only applicable to nested templates. If not specified, default value is outer.
mode	DeploymentMode	The mode that is used to deploy resources. This value can be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources.
onErrorDeployment	OnErrorDeployment	The deployment on error behavior.
parameters	object	Name and value pairs that define the deployment parameters for the template. You use this element when you want to provide the parameter values directly in the request rather than link to an existing parameter file. Use either the parametersLink property or the parameters property, but not both. It can be a JObject or a well formed JSON string.
parametersLink	ParametersLink	The URI of parameters file. You use this element to link to an existing parameters file. Use either the parametersLink property or the parameters property, but not both.
template	object	The template content. You use this element when you want to pass the template syntax directly in the request rather than link to an existing template. It can be a JObject or well-formed JSON string. Use either the templateLink property or the template property, but not both.
templateLink	TemplateLink	The URI of the template. Use either the templateLink property or the template property, but not both.

DeploymentPropertiesExtended

Deployment properties with additional details.

Name	Type	Description
correlationId	string	The correlation ID of the deployment.
debugSetting	DebugSetting	The debug setting of the deployment.
dependencies	Dependency[]	The list of deployment dependencies.
duration	string	The duration of the template deployment.
error	ErrorResponse	Error Response The deployment error.
mode	DeploymentMode	The deployment mode. Possible values are Incremental and Complete.
onErrorDeployment	OnErrorDeploymentExtended	The deployment on error behavior.
outputResources	ResourceReference[]	Array of provisioned resources.
outputs	object	Key/value pairs that represent deployment output.
parameters	object	Deployment parameters.
parametersLink	ParametersLink	The URI referencing the parameters.
providers	Provider[]	The list of resource providers needed for the deployment.
provisioningState	ProvisioningState	Denotes the state of provisioning.
templateHash	string	The hash produced for the template.
templateLink	TemplateLink	The URI referencing the template.
timestamp	string	The timestamp of the template deployment.
validatedResources	ResourceReference[]	Array of validated resources.

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorResponse

Error Response

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorResponse[]	The error details.
message	string	The error message.
target	string	The error target.

ExpressionEvaluationOptions

Specifies whether template expressions are evaluated within the scope of the parent template or nested template.

Name	Type	Description
scope	ExpressionEvaluationOptionsScopeType	The scope to be used for evaluation of parameters, variables and functions in a nested template.

ExpressionEvaluationOptionsScopeType

The scope to be used for evaluation of parameters, variables and functions in a nested template.

Name	Type	Description
Inner	string
NotSpecified	string
Outer	string

OnErrorDeployment

Deployment on error behavior.

Name	Type	Description
deploymentName	string	The deployment to be used on error case.
type	OnErrorDeploymentType	The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

OnErrorDeploymentExtended

Deployment on error behavior with additional details.

Name	Type	Description
deploymentName	string	The deployment to be used on error case.
provisioningState	string	The state of the provisioning for the on error deployment.
type	OnErrorDeploymentType	The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

OnErrorDeploymentType

The deployment on error behavior type. Possible values are LastSuccessful and SpecificDeployment.

Name	Type	Description
LastSuccessful	string
SpecificDeployment	string

ParametersLink

Entity representing the reference to the deployment parameters.

Name	Type	Description
contentVersion	string	If included, must match the ContentVersion in the template.
uri	string	The URI of the parameters file.

Provider

Resource provider information.

Name	Type	Description
id	string	The provider ID.
namespace	string	The namespace of the resource provider.
providerAuthorizationConsentState	ProviderAuthorizationConsentState	The provider authorization consent state.
registrationPolicy	string	The registration policy of the resource provider.
registrationState	string	The registration state of the resource provider.
resourceTypes	ProviderResourceType[]	The collection of provider resource types.

ProviderAuthorizationConsentState

The provider authorization consent state.

Name	Type	Description
Consented	string
NotRequired	string
NotSpecified	string
Required	string

ProviderExtendedLocation

The provider extended location.

Name	Type	Description
extendedLocations	string[]	The extended locations for the azure location.
location	string	The azure location.
type	string	The extended location type.

ProviderResourceType

Resource type managed by the resource provider.

Name	Type	Description
aliases	Alias[]	The aliases that are supported by this resource type.
apiProfiles	ApiProfile[]	The API profiles for the resource provider.
apiVersions	string[]	The API version.
capabilities	string	The additional capabilities offered by this resource type.
defaultApiVersion	string	The default API version.
locationMappings	ProviderExtendedLocation[]	The location mappings that are supported by this resource type.
locations	string[]	The collection of locations where this resource type can be created.
properties	object	The properties.
resourceType	string	The resource type.
zoneMappings	ZoneMapping[]

ProvisioningState

Denotes the state of provisioning.

Name	Type	Description
Accepted	string
Canceled	string
Created	string
Creating	string
Deleted	string
Deleting	string
Failed	string
NotSpecified	string
Ready	string
Running	string
Succeeded	string
Updating	string

ResourceReference

The resource Id model.

Name	Type	Description
id	string	The fully qualified resource Id.

TemplateLink

Entity representing the reference to the template.

Name	Type	Description
contentVersion	string	If included, must match the ContentVersion in the template.
id	string	The resource id of a Template Spec. Use either the id or uri property, but not both.
queryString	string	The query string (for example, a SAS token) to be used with the templateLink URI.
relativePath	string	The relativePath property can be used to deploy a linked template at a location relative to the parent. If the parent template was linked with a TemplateSpec, this will reference an artifact in the TemplateSpec. If the parent was linked with a URI, the child deployment will be a combination of the parent and relativePath URIs
uri	string	The URI of the template to deploy. Use either the uri or id property, but not both.

ZoneMapping

Name	Type	Description
location	string	The location of the zone mapping.
zones	string[]