Deployments - Create Or Update At Subscription Scope

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

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"
  }
}

Sample response

{
  "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": []
  }
}
{
  "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

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.

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[]