Funciones de recursos para plantillas de ARM

Resource Manager ofrece las siguientes funciones para obtener valores de recursos en la plantilla de Azure Resource Manager (plantilla de ARM):

• extensionResourceId
• list*
• pickZones
• providers (en desuso)
• reference
• resourceGroup
• resourceId
• suscripción
• subscriptionResourceId
• tenantResourceId

Para obtener valores de parámetro, variables o la implementación actual, consulte Funciones con valores de implementación.

extensionResourceId

extensionResourceId(baseResourceId, resourceType, resourceName1, [resourceName2], ...)

Devuelve el identificador de recurso de un recurso de extensión, que es un tipo de recurso que se aplica a otro recurso para agregarlo a sus capacidades.

Parámetros

Siga agregando nombres de recursos como parámetros cuando el tipo de recurso incluya más segmentos.

Valor devuelto

El formato básico del identificador de recurso devuelto por esta función es:

{scope}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

El segmento de ámbito varía según el recurso base que se está ampliando. Por ejemplo, el identificador de una suscripción tiene segmentos diferentes a los del identificador de un grupo de recursos.

Cuando el recurso de extensión se aplica a un recurso, el identificador de recurso se devuelve en el formato siguiente:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Cuando el recurso de extensión se aplica a un grupo de recursos, el formato devuelto es:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

En la sección siguiente se muestra un ejemplo del uso de esta función con un grupo de recursos.

Cuando el recurso de extensión se aplica a una suscripción, el formato devuelto es:

/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Cuando el recurso de extensión se aplica a un grupo de administración, el formato devuelto es:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

En la sección siguiente se muestra un ejemplo del uso de esta función con un grupo de administración.

Ejemplo de extensionResourceId

En el ejemplo siguiente se devuelve el identificador de recurso para el bloqueo de un grupo de recursos.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "lockName": {
      "type": "string"
    }
  },
  "variables": {},
  "resources": [],
  "outputs": {
    "lockResourceId": {
      "type": "string",
      "value": "[extensionResourceId(resourceGroup().Id , 'Microsoft.Authorization/locks', parameters('lockName'))]"
    }
  }
}

Una definición de directiva personalizada implementada en un grupo de administración se implementa como recurso de extensión. Para crear y asignar una directiva, implemente la siguiente plantilla en un grupo de administración.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.4.1.14562",
      "templateHash": "2350252618174097128"
    }
  },
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "functions": [],
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2020-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2020-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

Las definiciones de directivas integradas son recursos del nivel de inquilino. Para obtener un ejemplo de implementación de una definición de directiva integrada, consulte tenantResourceId.

lista*

list{Value}(resourceName or resourceIdentifier, apiVersion, functionValues)

La sintaxis de esta función varía según el nombre de las operaciones de la lista. Cada implementación devuelve valores para el tipo de recurso que admite una operación de la lista. El nombre de la operación debe empezar por list y tener un sufijo. Algunos usos habituales son list, listKeys, listKeyValue y listSecrets.

Parámetros

Usos válidos

Las funciones de lista se pueden usar en las propiedades de una definición de recursos. No use una función de lista que exponga información confidencial en la sección de salidas de una plantilla. Los valores de salida se almacenan en el historial de implementaciones y un usuario malintencionado podría recuperarlos.

Cuando se usa con la iteración de la propiedad, puede usar las funciones de lista para input porque la expresión se asigna a la propiedad de recurso. No se pueden utilizar con count porque debe determinarse el recuento antes de resolver la función de lista.

Implementaciones

Los usos posibles de la lista* se muestran en la tabla siguiente.

Para determinar qué tipos de recursos tienen una operación de lista, dispone de las siguientes opciones:

• Vea las operaciones de API de REST para un proveedor de recursos y busque operaciones List. Por ejemplo, las cuentas de almacenamiento tienen una operación listKeys.

• Utilice el cmdlet de PowerShell Get-AzProviderOperation. En el ejemplo siguiente se obtienen todas las operaciones List para cuentas de almacenamiento:

  Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
  

• Use el siguiente comando de la CLI de Azure para filtrar solo las operaciones de la lista:

  az provider operation show --namespace Microsoft.Storage --query "resourceTypes[?name=='storageAccounts'].operations[].name | [?contains(@, 'list')]"
  

Valor devuelto

El objeto devuelto varía según la función de la lista que use. Por ejemplo, listKeys para una cuenta de almacenamiento devuelve el siguiente formato:

{
  "keys": [
    {
      "keyName": "key1",
      "permissions": "Full",
      "value": "{value}"
    },
    {
      "keyName": "key2",
      "permissions": "Full",
      "value": "{value}"
    }
  ]
}

Otras funciones List tienen diferentes formatos de retorno. Para ver el formato de una función, inclúyalo en la sección de resultados tal y como se muestra en la plantilla de ejemplo.

Observaciones

Especifique el recursos con el nombre del recurso o la función resourceId. Al usar una función de la lista en la misma plantilla que implementa el recurso al que se hace referencia, use el nombre del recurso.

Si usa una función list con un recurso que se implementa de forma condicional, se puede evaluar la función incluso si el recurso no está implementado. Se genera un error si la función list hace referencia a un recurso que no existe. Use la función if para asegurarse de que la función se evalúa solo cuando se implementa el recurso. Consulte la función if function para una plantilla de ejemplo que use if y list con un recurso implementado de forma condicional.

Ejemplo de lista

En el ejemplo siguiente se usa listKeys al establecer un valor para los scripts de implementación.

"storageAccountSettings": {
  "storageAccountName": "[variables('storageAccountName')]",
  "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

En el ejemplo siguiente se muestra una función de lista que toma un parámetro. En este caso, la función se listAccountSas. Pase un objeto para la hora de expiración. Dicha hora debe ser futura.

"parameters": {
  "accountSasProperties": {
    "type": "object",
    "defaultValue": {
      "signedServices": "b",
      "signedPermission": "r",
      "signedExpiry": "2020-08-20T11:00:00Z",
      "signedResourceTypes": "s"
    }
  }
},
...
"sasToken": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties')).accountSasToken]"

pickZones

pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])

Determina si un tipo de recurso admite zonas para la ubicación o región especificada. Esta función solo admite recursos de zona; los servicios con redundancia de zona devolverán una matriz vacía. Para obtener más información, consulte Servicios compatibles con Availability Zones. Para usar la función pickZones con servicios con redundancia de zona, consulte los siguientes ejemplos.

Parámetros

Valor devuelto

Matriz con las zonas admitidas. Cuando se usan los valores predeterminados para offset y numberOfZones, un tipo de recurso y una región que admiten zonas devuelven la siguiente matriz:

[
    "1"
]

Cuando el parámetro numberOfZones se establece en 3, devuelve lo siguiente:

[
    "1",
    "2",
    "3"
]

Si el tipo de recurso o la región no admiten zonas, se devuelve una matriz vacía. También se devuelve una matriz vacía para los servicios con redundancia de zona.

[
]

Comentarios

Hay distintas categorías para Azure Availability Zones: zonal y con redundancia de zona. La función pickZones se puede usar para devolver un número de zona de disponibilidad o números para un recurso de zona. Eb el caso de servicios con redundancia de zona (ZRS), la función devolverá una matriz vacía. Normalmente, los recursos zonales se pueden identificar mediante el uso de una propiedad zones en el encabezado de recurso. Los servicios con redundancia de zona tienen diferentes maneras de identificar y usar zonas de disponibilidad por recurso. Consulte la documentación de un servicio específico para determinar la categoría de compatibilidad con zonas de disponibilidad. Para obtener más información, consulte Servicios compatibles con Availability Zones.

Para determinar si una determinada región o ubicación de Azure admite zonas de disponibilidad, llame a la función pickZones() con un tipo de recurso zonal, por ejemplo, Microsoft.Storage/storageAccounts. Si la respuesta no está vacía, la región admite zonas de disponibilidad.

Ejemplo de pickZones

En la plantilla siguiente se muestran tres resultados para usar la función pickZones.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "functions": [],
  "variables": {},
  "resources": [],
  "outputs": {
    "supported": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')]"
    },
    "notSupportedRegion": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'northcentralus')]"
    },
    "notSupportedType": {
      "type": "array",
      "value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
    }
  }
}

La salida de los ejemplos anteriores devuelve tres matrices.

Puede usar la respuesta de pickZones para determinar si se debe proporcionar un valor null para las zonas o asignar máquinas virtuales a diferentes zonas. En el ejemplo siguiente se establece un valor para la zona en función de la disponibilidad de las zonas.

"zones": {
  "value": "[if(not(empty(pickZones('Microsoft.Compute', 'virtualMachines', 'westus2'))), string(add(mod(copyIndex(),3),1)), json('null'))]"
},

En el siguiente ejemplo se muestra cómo usar la función pickZones con el fin de habilitar la redundancia de zona para Cosmos DB.

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2021-04-15",
    "name": "[variables('accountName_var')]",
    "location": "[parameters('location')]",
    "kind": "GlobalDocumentDB",
    "properties": {
      "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
      "locations": [
        {
          "locationName": "[parameters('primaryRegion')]",
          "failoverPriority": 0,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
        },
        {
          "locationName": "[parameters('secondaryRegion')]",
          "failoverPriority": 1,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
        }
      ],
      "databaseAccountOfferType": "Standard",
      "enableAutomaticFailover": "[parameters('automaticFailover')]"
    }
  }
]

providers

La función providers está en desuso. Por tanto, no se recomienda utilizarla. Si usó esta función para obtener una versión de la API para el proveedor de recursos, se recomienda proporcionar una versión de API específica en la plantilla. El uso de una versión de API devuelta dinámicamente puede interrumpir la plantilla si las propiedades cambian entre versiones.

reference

reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])

Devuelve un objeto que representa el estado de tiempo de ejecución de un recurso.

Parámetros

Valor devuelto

Cada tipo de recurso devuelve propiedades diferentes para la función de referencia. La función no devuelve un solo formato predefinido. Además, el valor devuelto difiere en función del valor del argumento 'Full'. Para ver las propiedades de un tipo de recurso, devuelva el objeto en la sección de resultados tal como se muestra en el ejemplo.

Observaciones

La función de referencia recupera el estado del entorno de ejecución de un recurso previamente implementado o de un recurso implementado en la plantilla actual. En este artículo se muestran ejemplos de ambos escenarios.

Normalmente, se usa la función de reference para devolver un valor determinado de un objeto, como el identificador URI del punto de conexión de blob o el nombre de dominio completo.

"outputs": {
  "BlobUri": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))).primaryEndpoints.blob]"
  },
  "FQDN": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName'))).dnsSettings.fqdn]"
  }
}

Utilice 'Full' cuando necesite valores de recurso que no forman parte del esquema de propiedades. Por ejemplo, para establecer directivas de acceso del almacén de claves, obtenga las propiedades de identidad para una máquina virtual.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2019-09-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

Usos válidos

La función de referencia solo se puede utilizar en las propiedades de una definición de recursos y en la sección de salidas de una plantilla o implementación. Cuando se usa con la iteración de la propiedad, puede usar la función reference para input porque la expresión se asigna a la propiedad de recurso.

No se puede utilizar la función reference para establecer el valor de la propiedad count en un bucle de copia. Puede usarla para establecer otras propiedades en el bucle. La referencia está bloqueada para la propiedad count, porque esa propiedad se debe determinar antes de que se resuelva la función reference.

Para usar la función reference o cualquier función list* en la sección de salidas de una plantilla anidada, debe establecer expressionEvaluationOptions para usar la evaluación de ámbito interno o una plantilla vinculada en lugar de una anidada.

Si usa una función reference con un recurso que se implementa de forma condicional, se puede evaluar la función incluso si el recurso no está implementado. Se genera un error si la función reference hace referencia a un recurso que no existe. Use la función if para asegurarse de que la función se evalúa solo cuando se implementa el recurso. Consulte la función if para una plantilla de ejemplo que use if y reference con un recurso implementado de forma condicional.

Dependencia implícita

Mediante el uso de la función de referencia, se declara implícitamente que un recurso depende de otro recurso si el recurso al que se hace referencia se aprovisiona en la misma plantilla y se hace referencia a él por su nombre (y no por el identificador del recurso). No tiene que usar también la propiedad dependsOn. La función no se evalúa hasta que el recurso al que se hace referencia haya completado la implementación.

Nombre de recurso o identificador

Al hacer referencia a un recurso que esté implementado en la misma plantilla, especifique el nombre del recurso.

"value": "[reference(parameters('storageAccountName'))]"

Al hacer referencia a un recurso que no esté implementado en la misma plantilla, especifique el identificador del recurso y apiVersion.

"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2018-07-01')]"

Para evitar la ambigüedad sobre cuál es el recurso al que hace referencia, puede proporcionar un nombre de recurso completo.

"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName')))]"

Al construir una referencia completa a un recurso, el orden para combinar los segmentos a partir del tipo y el nombre no es simplemente una concatenación de los dos. En su lugar, después del espacio de nombres, use una secuencia de pares tipo/nombre de menos a más específico:

{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]

Por ejemplo:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt es correcto Microsoft.Compute/virtualMachines/extensions/myVM/myExt no es correcto

Para simplificar la creación de cualquier identificador de recurso, use las funciones resourceId() descritas en este documento, en lugar de la función concat().

Obtención de una identidad administrada

Las identidades administradas para los recursos de Azure son tipos de recursos de extensión que se crean implícitamente para algunos recursos. Dado que la identidad administrada no se define explícitamente en la plantilla, debe hacer referencia al recurso al que se aplica la identidad. Utilice Full para obtener todas las propiedades, incluida la identidad creada implícitamente.

El patrón es:

"[reference(resourceId(<resource-provider-namespace>, <resource-name>), <API-version>, 'Full').Identity.propertyName]"

Por ejemplo, para obtener el identificador de la entidad de seguridad de una identidad administrada que se aplica a una máquina virtual, use:

"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",

O bien, para obtener el identificador de inquilino de una identidad administrada que se aplica a un conjunto de escalado de máquinas virtuales, use:

"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets',  variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"

Ejemplo de referencia

En el ejemplo siguiente se implementa un recurso y se hace referencia a ese recurso.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2021-04-01', 'Full')]"
    }
  }
}

El ejemplo anterior devuelve los dos objetos. El objeto de propiedades está en el formato siguiente:

{
   "creationTime": "2017-10-09T18:55:40.5863736Z",
   "primaryEndpoints": {
     "blob": "https://examplestorage.blob.core.windows.net/",
     "file": "https://examplestorage.file.core.windows.net/",
     "queue": "https://examplestorage.queue.core.windows.net/",
     "table": "https://examplestorage.table.core.windows.net/"
   },
   "primaryLocation": "southcentralus",
   "provisioningState": "Succeeded",
   "statusOfPrimary": "available",
   "supportsHttpsTrafficOnly": false
}

El objeto completo está en el formato siguiente:

{
  "apiVersion":"2021-04-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2017-10-09T18:55:40.5863736Z",
    "primaryEndpoints": {
      "blob":"https://examplestorage.blob.core.windows.net/",
      "file":"https://examplestorage.file.core.windows.net/",
      "queue":"https://examplestorage.queue.core.windows.net/",
      "table":"https://examplestorage.table.core.windows.net/"
    },
    "primaryLocation":"southcentralus",
    "provisioningState":"Succeeded",
    "statusOfPrimary":"available",
    "supportsHttpsTrafficOnly":false
  },
  "subscriptionId":"<subscription-id>",
  "resourceGroupName":"functionexamplegroup",
  "resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
  "referenceApiVersion":"2021-04-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

En la plantilla de ejemplo siguiente se hace referencia a una cuenta de almacenamiento que no se implementa en esta plantilla. La cuenta de almacenamiento ya existe dentro de la misma suscripción.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageResourceGroup": {
      "type": "string"
    },
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [],
  "outputs": {
    "ExistingStorage": {
      "type": "object",
      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
    }
  }
}

resourceGroup

resourceGroup()

Devuelve un objeto que representa el grupo de recursos actual.

Valor devuelto

El objeto devuelto está en el formato siguiente:

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
  "name": "{resourceGroupName}",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "{resourceGroupLocation}",
  "managedBy": "{identifier-of-managing-resource}",
  "tags": {
  },
  "properties": {
    "provisioningState": "{status}"
  }
}

La propiedad managedBy solo se devuelve para los grupos de recursos que contienen recursos administrados por otro servicio. En los casos de Managed Applications, Databricks y AKS, el valor de la propiedad es el identificador del recurso que realiza la administración.

Observaciones

La función resourceGroup() no se puede usar en una plantilla que está implementada en el nivel de suscripción. Solo puede usarse en las plantillas que se implementan en un grupo de recursos. Puede usar la resourceGroup()función en una plantilla vinculada o anidada (con ámbito interno) que tenga como destino un grupo de recursos, incluso cuando la plantilla primaria se implementa en la suscripción. En ese escenario, la plantilla vinculada o anidada se implementa en el nivel de grupo de recursos. Para más información sobre cómo establecer como destino un grupo de recursos en una implementación de nivel de suscripción, consulte Implementar recursos de Azure en más de una suscripción o un grupo de recursos.

Un uso común de la función resourceGroup es crear recursos en la misma ubicación que el grupo de recursos. En el ejemplo siguiente se utiliza la ubicación del grupo de recursos para un valor de parámetro predeterminado.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

También puede usar la función resourceGroup para aplicar etiquetas del grupo de recursos a un recurso. Para más información, consulte Aplicación de etiquetas de un grupo de recursos.

Al usar plantillas anidadas para implementar en varios grupos de recursos, puede especificar el ámbito para evaluar la función resourceGroup. Para más información, consulte Implementación de recursos de Azure en varias suscripciones y grupos de recursos.

Ejemplo de grupo de recursos

En el ejemplo siguiente se devuelven las propiedades del grupo de recursos.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "resourceGroupOutput": {
      "type": "object",
      "value": "[resourceGroup()]"
    }
  }
}

El ejemplo anterior devuelve un objeto en el formato siguiente:

{
  "id": "/subscriptions/{subscription-id}/resourceGroups/examplegroup",
  "name": "examplegroup",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "southcentralus",
  "properties": {
    "provisioningState": "Succeeded"
  }
}

resourceId

resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)

Devuelve el identificador único de un recurso. Utilice esta función cuando el nombre del recurso sea ambiguo o no esté aprovisionado dentro de la misma plantilla. El formato del identificador devuelto varía en función de si la implementación se produce en el ámbito de un grupo de recursos, una suscripción, un grupo de administración o un inquilino.

Parámetros

Siga agregando nombres de recursos como parámetros cuando el tipo de recurso incluya más segmentos.

Valor devuelto

Cuando la plantilla se implementa en el ámbito de un grupo de recursos, el identificador de recurso se devuelve en el formato siguiente:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Puede usar la función resourceId para otros ámbitos de implementación, pero cambia el formato del id.

Si usa resourceId durante la implementación en una suscripción, el id. de recurso se devuelve en el formato siguiente:

/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Si usa resourceId durante la implementación en un grupo de administración o inquilino, el id. de recurso se devuelve en el formato siguiente:

/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Para evitar confusiones, no se recomienda usar resourceId al trabajar con recursos implementados en la suscripción, el grupo de administración o el inquilino. En su lugar, use la función de id. que se diseñó para el ámbito.

En el caso de los recursos del nivel de suscripción, use la función subscriptionResourceId().

En el caso de los recursos del nivel de grupo de administración, use la función extensionResourceId para hacer referencia a un recurso que se implementa como extensión de un grupo de administración. Por ejemplo, las definiciones de directivas personalizadas que se implementan en un grupo de administración son extensiones del grupo de administración. Use la función tenantResourceId para hacer referencia a los recursos que se implementan en el inquilino, pero están disponibles en el grupo de administración. Por ejemplo, las definiciones de directivas integradas se implementan como recursos de nivel de inquilino.

En el caso de los recursos de nivel de inquilino, use la función tenantResourceId. Use tenantResourceId para las definiciones de directiva integradas, ya que se implementan en el nivel de inquilino.

Observaciones

El número de parámetros que proporcione varía en función de si el recurso es primario o secundario, y de si está en la misma suscripción o grupo de recursos.

Para obtener el Id. de un recurso primario de la misma suscripción y grupo de recursos, proporcione el tipo y el nombre del recurso.

"[resourceId('Microsoft.ServiceBus/namespaces', 'namespace1')]"

Para obtener el Id. de un recurso secundario, preste atención al número de segmentos en el tipo de recurso. Proporcione un nombre de recurso para cada segmento del tipo de recurso. El nombre del segmento corresponde al recurso que existe para esa parte de la jerarquía.

"[resourceId('Microsoft.ServiceBus/namespaces/queues/authorizationRules', 'namespace1', 'queue1', 'auth1')]"

Para obtener el Id. de un recurso de la misma suscripción en un grupo de recursos distinto, proporcione el nombre del grupo de recursos.

"[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts', 'examplestorage')]"

Para obtener el Id. de un recurso con una suscripción y grupo de recursos distintos, proporcione el Id. de suscripción y el nombre del grupo de recursos.

"[resourceId('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"

A menudo, necesitará utilizar esta función cuando se usa una cuenta de almacenamiento o red virtual en un grupo de recursos alternativo. En el ejemplo siguiente se muestra cómo un recurso de un grupo de recursos externos se puede utilizar fácilmente:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "virtualNetworkName": {
      "type": "string"
    },
    "virtualNetworkResourceGroup": {
      "type": "string"
    },
    "subnet1Name": {
      "type": "string"
    },
    "nicName": {
      "type": "string"
    }
  },
  "variables": {
    "subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
  },
  "resources": [
    {
      "type": "Microsoft.Network/networkInterfaces",
      "apiVersion": "2021-02-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Ejemplo de identificador de recursos

En el ejemplo siguiente se devuelve el identificador de recurso de la cuenta de almacenamiento en el grupo de recursos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "sameRGOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentRGOutput": {
      "type": "string",
      "value": "[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentSubOutput": {
      "type": "string",
      "value": "[resourceId('11111111-1111-1111-1111-111111111111', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "nestedResourceOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.SQL/servers/databases', 'serverName', 'databaseName')]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

subscription

subscription()

Devuelve detalles sobre la suscripción para la implementación actual.

Valor devuelto

La función devuelve el siguiente formato:

{
  "id": "/subscriptions/{subscription-id}",
  "subscriptionId": "{subscription-id}",
  "tenantId": "{tenant-id}",
  "displayName": "{name-of-subscription}"
}

Observaciones

Al usar plantillas anidadas para implementar en varias suscripciones, puede especificar el ámbito para evaluar la función de suscripción. Para más información, consulte Implementación de recursos de Azure en varias suscripciones y grupos de recursos.

Ejemplo de suscripción

En el ejemplo siguiente se muestra la función de suscripción a la que se llama en la sección de salidas.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "subscriptionOutput": {
      "type": "object",
      "value": "[subscription()]"
    }
  }
}

subscriptionResourceId

subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)

Devuelve el identificador único de un recurso implementado en el nivel de suscripción.

Parámetros

Siga agregando nombres de recursos como parámetros cuando el tipo de recurso incluya más segmentos.

Valor devuelto

El identificador se devuelve con el formato siguiente:

/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Observaciones

Utilice esta función para obtener el identificador de recurso de los recursos que se implementan en la suscripción en lugar de en un grupo de recursos. El identificador devuelto difiere del valor devuelto por la función resourceId en que no incluye un valor de grupo de recursos.

Ejemplo de subscriptionResourceId

La siguiente plantilla asigna un rol integrado. Puede implementarlo en un grupo de recursos o en una suscripción. Usa la función subscriptionResourceId para obtener el id. de recurso de los recursos integrados.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The principal to assign the role to"
      }
    },
    "builtInRoleType": {
      "type": "string",
      "allowedValues": [
        "Owner",
        "Contributor",
        "Reader"
      ],
      "metadata": {
        "description": "Built-in role to assign"
      }
    },
    "roleNameGuid": {
      "type": "string",
      "defaultValue": "[newGuid()]",
      "metadata": {
        "description": "A new GUID used to identify the role assignment"
      }
    }
  },
  "variables": {
    "Owner": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
    "Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
    "Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2020-10-01-preview",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

tenantResourceId

tenantResourceId(resourceType, resourceName1, [resourceName2], ...)

Devuelve el identificador único de un recurso implementado en el nivel de inquilino.

Parámetros

Siga agregando nombres de recursos como parámetros cuando el tipo de recurso incluya más segmentos.

Valor devuelto

El identificador se devuelve con el formato siguiente:

/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Observaciones

Esta función se usa para obtener el identificador de recurso de un recurso que se implementa en el inquilino. El identificador devuelto difiere de los valores devueltos por otras funciones de identificador de recurso en que no incluye los valores de un grupo de recursos o una suscripción.

Ejemplo de tenantResourceId

Las definiciones de directivas integradas son recursos del nivel de inquilino. Para implementar una asignación de directiva que hace referencia a una definición de directiva integrada, use la función tenantResourceId.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "policyDefinitionID": {
      "type": "string",
      "defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
      "metadata": {
        "description": "Specifies the ID of the policy definition or policy set definition being assigned."
      }
    },
    "policyAssignmentName": {
      "type": "string",
      "defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
      "metadata": {
        "description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "name": "[parameters('policyAssignmentName')]",
      "apiVersion": "2020-09-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Pasos siguientes

• Puede encontrar una descripción de las secciones de una plantilla de Azure Resource Manager en Nociones sobre la estructura y la sintaxis de las plantillas de Resource Manager.
• Para combinar varias plantillas, consulte Uso de plantillas vinculadas y anidadas al implementar recursos de Azure.
• Para iterar un número especificado de veces al crear un tipo de recurso, consulte Iteración de recursos en las plantillas de Resource Manager.
• Para ver cómo implementar la plantilla que ha creado, consulte Implementación de recursos con plantillas de Resource Manager y Azure PowerShell.