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)
• referencia
• references
• resourceId
• subscriptionResourceId
• managementGroupResourceId
• tenantResourceId

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

Para obtener valores de ámbito de implementación, vea Funciones de ámbito.

Sugerencia

Se recomienda Bicep porque ofrece las mismas funcionalidades que las plantillas de ARM y la sintaxis es más fácil de usar. Para más información, consulte las funciones de recurso.

extensionResourceId

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

Devuelve el id. de recurso de un recurso de extensión. Un recurso de extensión es un tipo de recurso que se aplica a otro para agregarlo a sus funcionalidades.

En Bicep, use la función extensionResourceId.

Parámetros

Parámetro	Obligatorio	Type	Descripción
baseResourceId	Sí	string	El identificador de recurso para el recurso al que se aplica el recurso de extensión.
resourceType	Sí	string	Tipo de recurso de extensión, incluido el espacio de nombres del proveedor de recursos.
resourceName1	Sí	string	Nombre del recurso de extensión.
resourceName2	No	string	Segmento con el nombre del siguiente segmento, si es necesario.

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.5.6.12127",
      "templateHash": "1532257987028557958"
    }
  },
  "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."
      }
    }
  },
  "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": [
        "[extensionResourceId(managementGroup().id, 'Microsoft.Authorization/policyDefinitions', 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.

En Bicep, use la función list*.

Parámetros

Parámetro	Obligatorio	Type	Descripción
resourceName o resourceIdentifier	Sí	string	Identificador único para el recurso.
apiVersion	Sí	string	Versión de API de estado en tiempo de ejecución de un recurso. Por lo general, en el formato, aaaa-mm-dd.
functionValues	No	object	Un objeto que tiene valores para la función. Proporcione este objeto solo para las funciones que admiten la recepción de un objeto con valores de parámetro, como listAccountSas en una cuenta de almacenamiento. En este artículo se muestra un ejemplo de cómo pasar los valores de funciones.

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 list* se muestran en la tabla siguiente.

Tipo de recurso	Nombre de función
Microsoft.Addons/supportProviders	listsupportplaninfo
Microsoft.AnalysisServices/servers	listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers	listSecrets
Microsoft.ApiManagement/service/gateways	listKeys
Microsoft.ApiManagement/service/identityProviders	listSecrets
Microsoft.ApiManagement/service/namedValues	listValue
Microsoft.ApiManagement/service/openidConnectProviders	listSecrets
Microsoft.ApiManagement/service/subscriptions	listSecrets
Microsoft.AppConfiguration/configurationStores	ListKeys
Microsoft.AppPlatform/Spring	listTestKeys
Microsoft.Automation/automationAccounts	listKeys
Microsoft.Batch/batchAccounts	listKeys
Microsoft.BatchAI/workspaces/experiments/jobs	listoutputfiles
Microsoft.BotService/botServices/channels	listChannelWithKeys
Microsoft.Cache/redis	listKeys
Microsoft.CognitiveServices/accounts	listKeys
Microsoft.ContainerRegistry/registries	listCredentials
Microsoft.ContainerRegistry/registries	listUsages
Microsoft.ContainerRegistry/registries/agentpools	listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks	listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps	listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns	listDetails
Microsoft.ContainerRegistry/registries/webhooks	listEvents
Microsoft.ContainerRegistry/registries/runs	listLogSasUrl
Microsoft.ContainerRegistry/registries/tasks	listDetails
Microsoft.ContainerService/managedClusters	listClusterAdminCredential
Microsoft.ContainerService/managedClusters	listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters	listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles	listCredential
Microsoft.DataBox/jobs	listCredentials
Microsoft.DataFactory/datafactories/gateways	listauthkeys
Microsoft.DataFactory/factories/integrationruntimes	listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers	listSasTokens
Microsoft.DataShare/accounts/shares	listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions	listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions	listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions	listSynchronizations
Microsoft.Devices/iotHubs	listKeys
Microsoft.Devices/iotHubs/iotHubKeys	listKeys
Microsoft.Devices/provisioningServices/keys	listKeys
Microsoft.Devices/provisioningServices	listKeys
Microsoft.DevTestLab/labs	ListVhds
Microsoft.DevTestLab/labs/schedules	ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics	ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines	ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts	listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces	listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains	listAgreements
Microsoft.EventHub/namespaces/authorizationRules	listKeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules	listKeys
Microsoft.ImportExport/jobs	listBitLockerKeys
Microsoft.Kusto/Clusters/Databases	ListPrincipals
Microsoft.LabServices/labs/users	list
Microsoft.LabServices/labs/virtualMachines	list
Microsoft.Logic/integrationAccounts/agreements	listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assemblies	listContentCallbackUrl
Microsoft.Logic/integrationAccounts	listCallbackUrl
Microsoft.Logic/integrationAccounts	listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps	listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners	listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas	listContentCallbackUrl
Microsoft.Logic/workflows	listCallbackUrl
Microsoft.Logic/workflows	listSwagger
Microsoft.Logic/workflows/runs/actions	listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions	listExpressionTraces
Microsoft.Logic/workflows/triggers	listCallbackUrl
Microsoft.Logic/workflows/versions/triggers	listCallbackUrl
Microsoft.MachineLearning/webServices	listkeys
Microsoft.MachineLearning/Workspaces	listworkspacekeys
Microsoft.Maps/accounts	listKeys
Microsoft.Media/mediaservices/assets	listContainerSas
Microsoft.Media/mediaservices/assets	listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators	listContentKeys
Microsoft.Media/mediaservices/streamingLocators	listPaths
Microsoft.Network/applicationSecurityGroups	listIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRules	listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules	listkeys
Microsoft.OperationalInsights/workspaces	list
Microsoft.OperationalInsights/workspaces	listKeys
Microsoft.PolicyInsights/remediations	listDeployments
Microsoft.RedHatOpenShift/openShiftClusters	listCredentials
Microsoft.Relay/namespaces/authorizationRules	listKeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.Relay/namespaces/HybridConnections/authorizationRules	listKeys
Microsoft.Relay/namespaces/WcfRelays/authorizationRules	listkeys
Microsoft.Search/searchServices	listAdminKeys
Microsoft.Search/searchServices	listQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRules	listKeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.ServiceBus/namespaces/queues/authorizationRules	listKeys
Microsoft.SignalRService/SignalR	listKeys
Microsoft.Storage/storageAccounts	listAccountSas
Microsoft.Storage/storageAccounts	listKeys
Microsoft.Storage/storageAccounts	listServiceSas
Microsoft.StorSimple/managers/devices	listFailoverSets
Microsoft.StorSimple/managers/devices	listFailoverTargets
Microsoft.StorSimple/managers	listActivationKey
Microsoft.StorSimple/managers	listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes	listAuthKeys
Microsoft.Web/connectionGateways	ListStatus
microsoft.web/connections	listconsentlinks
Microsoft.Web/customApis	listWsdlInterfaces
microsoft.web/locations	listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections	listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections	listSecrets
microsoft.web/sites/backups	list
Microsoft.Web/sites/config	list
microsoft.web/sites/functions	listKeys
microsoft.web/sites/functions	listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays	listKeys
microsoft.web/sites	listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions	listSecrets
microsoft.web/sites/slots/backups	list
Microsoft.Web/sites/slots/config	list
microsoft.web/sites/slots/functions	listSecrets

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.

• Use el cmdlet de PowerShell Get-​AzProvider​Operation. 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 list que use. Por ejemplo, listKeys para una cuenta de almacenamiento devuelve el formato siguiente:

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

Otras funciones list tienen otros formatos de devolución. 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 list 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 con 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 list que toma un parámetro. En este caso, la función es 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 zonales. Los servicios con redundancia de zona devuelven una matriz vacía. Para obtener más información, consulte Servicios compatibles con Availability Zones.

En Bicep, use la función pickZones.

Parámetros

Parámetro	Obligatorio	Type	Descripción
providerNamespace	Sí	string	Espacio de nombres del proveedor de recursos para que el tipo de recurso compruebe la compatibilidad de la zona.
resourceType	Sí	string	El tipo de recurso para comprobar la compatibilidad de la zona.
ubicación	Sí	string	Región en la que se va a comprobar la compatibilidad de la zona.
numberOfZones	No	integer	Número de zonas lógicas que se van a devolver. El valor predeterminado es 1. El número debe ser un entero positivo de 1 a 3. Use 1 para los recursos de una sola zona. En el caso de los recursos de varias zonas, el valor debe ser menor o igual que el número de zonas admitidas.
offset	No	integer	Desplazamiento de la zona lógica inicial. La función devuelve un error si el desplazamiento más el valor de numberOfZones supera el número de zonas admitidas.

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 una zona de disponibilidad para un recurso zonal. En el caso de servicios con redundancia de zona (ZRS), la función devuelve una matriz vacía. Los recursos zonales suelen tener una propiedad zones en el nivel superior de la definición del recurso. Para determinar la categoría de soporte técnico para las zonas de disponibilidad, vea Servicios de Azure 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.Network/publicIPAddresses. 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', 'westus')]"
    },
    "notSupportedType": {
      "type": "array",
      "value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
    }
  }
}

La salida de los ejemplos anteriores devuelve tres matrices.

Nombre	Tipo	Value
admitido	array	[ "1" ]
notSupportedRegion	array	[]
notSupportedType	array	[]

Puede usar la respuesta de pickZones a fin de determinar si se debe proporcionar un valor NULL para las zonas o asignar máquinas virtuales a otras 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'))]"
},

Azure Cosmos DB no es un recurso zonal, pero puede usar la función pickZones para determinar si se debe habilitar la redundancia de zona para la replicación geográfica. Pase el tipo de recurso Microsoft.Storage/storageAccounts para determinar si se debe habilitar la redundancia de zona.

"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 proveedores está en desuso en las plantillas de ARM. 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.

En Bicep, la función providers está en desuso.

La operación de proveedores sigue estando disponible a través de la API REST. Se puede usar fuera de una plantilla de ARM para obtener información sobre un proveedor de recursos.

reference

En las plantillas sin nombres simbólicos:

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

En las plantillas con nombres simbólicos:

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

Devuelve un objeto que representa el estado de tiempo de ejecución de un recurso. La salida y el comportamiento de la función reference se basan en gran medida en cómo cada proveedor de recursos (RP) implementa sus respuestas PUT y GET. Para devolver una matriz de objetos que representan los estados en tiempo de ejecución de una colección de recursos, consulte referencias.

Bicep proporciona la función de referencia, pero, en la mayoría de los casos, la función de referencia no es necesaria. Se recomienda usar el nombre simbólico del recurso en su lugar. Consulte la fuente.

Parámetros

Parámetro	Obligatorio	Type	Descripción
resourceName/resourceIdentifier o symbolicName/resourceIdentifier	Sí	cadena	En las plantillas sin nombres simbólicos, especifique el nombre o el identificador único de un recurso. Al hacer referencia a un recurso en la plantilla actual, proporcione solo el nombre del recurso como parámetro. Al hacer referencia a un recurso implementado anteriormente o cuando el nombre del recurso sea ambiguo, proporcione el identificador del recurso. En las plantillas con nombres simbólicos, especifique el nombre simbólico o el identificador único de un recurso. Al hacer referencia a un recurso en la plantilla actual, proporcione solo el nombre del recurso simbólicos como parámetro. Al hacer referencia a un recurso implementado previamente, especifique el identificador del recurso.
apiVersion	No	string	Versión de la API del recurso especificado. Este parámetro es necesario no está aprovisionado dentro de la misma plantilla. Por lo general, en el formato, aaaa-mm-dd. Para conocer las versiones válidas de la API para su recurso, consulte la referencia de la plantilla.
'Full'	No	string	Valor que especifica si se devuelve el objeto de recurso completo. Si no se especifica 'Full', se devuelve solo el objeto de propiedades del recurso. El objeto completo incluye valores como el identificador de recurso y la ubicación.

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": "2022-07-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 reference solo se puede usar en la sección de salidas de una plantilla o en un objeto de implementación y propiedades de una definición de recurso. No se puede usar para propiedades de recursos como type, name, location y otras propiedades de nivel superior de la definición de recursos. 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 usar 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 con 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 reference, se declara implícitamente que un recurso depende de otro 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 del recurso, nombre simbólico o identificador

Cuando haga referencia a un recurso implementado en la misma plantilla sin nombre simbólico, indique el nombre del recurso.

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

Cuando haga referencia a un recurso implementado en la misma plantilla de nombre simbólico, indique el nombre simbólico del recurso.

"value": "[reference('myStorage').primaryEndpoints]"

Or

"value": "[reference('myStorage', '2022-09-01', 'Full').location]"

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')), '2022-09-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"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2022-09-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":"2022-09-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2021-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')]"
    }
  }
}

references

references(symbolic name of a resource collection, ['Full', 'Properties])

La función references opera de forma similar a reference. En lugar de devolver un objeto que presenta el estado en tiempo de ejecución de un recurso, la función references devuelve una matriz de objetos que representan los estados en tiempo de ejecución de una colección de recursos. Esta función requiere la versión 2.0 del lenguaje de plantilla de ARM y con el nombre simbólico habilitado:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  ...
}

En Bicep no hay ninguna función references explícita. En su lugar, se emplea directamente el uso de la colección simbólica y, durante la generación de código, Bicep lo traduce a una plantilla de ARM que usa la función references de plantilla de ARM. Para obtener más información, vea Referencia a colecciones de recursos o módulos.

Parámetros

Parámetro	Obligatorio	Type	Descripción
Nombre simbólico de una colección de recursos	Sí	cadena	Nombre simbólico de una colección de recursos definida en la plantilla actual. La función references no admite la referencia a recursos externos a la plantilla actual.
"Full", "Properties"	No	cadena	Valor que especifica si se devuelve una matriz de los objetos del recurso completo. El valor predeterminado es 'Properties'. Si no se especifica 'Full', se devolverán solo los objetos de propiedades de los recursos. El objeto completo incluye valores como el identificador de recurso y la ubicación.

Valor devuelto

Matriz de la colección de recursos. Cada tipo de recurso devuelve propiedades diferentes para la función reference. Además, el valor devuelto difiere en función del valor del argumento 'Full'. Para obtener más información, consulte la referencia.

La salida de references siempre se organiza en orden ascendente en función del índice de copia. Por lo tanto, el primer recurso de la colección con el índice 0 se muestra primero, seguido del índice 1, etc. Por ejemplo, [trabajo-0, trabajo-1, trabajo-2…].

En el ejemplo anterior, si se implementan trabajo-0 y trabajo-2, mientras que trabajo-1 no lo hace debido a una condición falsa, la salida de references omitirá el recurso no implementado y mostrará los implementados, ordenados por sus números. La salida de references será [trabajo-0, trabajo-2, ...]. Si se omiten todos los recursos, la función devolverá una matriz vacía.

Usos válidos

La función references no se puede usar dentro de bucles de copia de recursos ni dentro de un bucle for de Bicep. Por ejemplo, references no se permite en el escenario siguiente:

{
  resources: {
    "resourceCollection": {
       "copy": { ... },
       "properties": {
         "prop": "[references(...)]"
       }
    }
  }
}

Para usar la función references 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.

Dependencia implícita

Al usar la función references, se declara implícitamente que un recurso depende de otro 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.

Ejemplo de referencia

En el ejemplo siguiente se implementa una colección de recursos y se hace referencia a esa colección de recursos.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "numWorkers": {
      "type": "int",
      "defaultValue": 4,
      "metadata": {
        "description": "The number of workers"
      }
    }
  },
  "resources": {
    "containerWorkers": {
      "copy": {
        "name": "containerWorkers",
        "count": "[length(range(0, parameters('numWorkers')))]"
      },
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
            "properties": {
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      }
    },
    "containerController": {
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "controller",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "controller-container",
            "properties": {
              "command": [
                "echo",
                "[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
              ],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      },
      "dependsOn": [
        "containerWorkers"
      ]
    }
  },
  "outputs": {
    "workerIpAddresses": {
      "type": "string",
      "value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
    },
    "containersFull": {
      "type": "array",
      "value": "[references('containerWorkers', 'full')]"
    },
    "container": {
      "type": "array",
      "value": "[references('containerWorkers')]"
    }
  }
}

El ejemplo anterior devuelve los tres objetos.

"outputs": {
  "workerIpAddresses": {
    "type": "String",
    "value": "20.66.74.26,20.245.100.10,13.91.86.58,40.83.249.30"
  },
  "containersFull": {
    "type": "Array",
    "value": [
      {
        "apiVersion": "2023-05-01",
        "condition": true,
        "copyContext": {
          "copyIndex": 0,
          "copyIndexes": {
            "": 0,
            "containerWorkers": 0
          },
          "name": "containerWorkers"
        },
        "copyLoopSymbolicName": "containerWorkers",
        "deploymentResourceLineInfo": {
          "lineNumber": 30,
          "linePosition": 25
        },
        "existing": false,
        "isAction": false,
        "isConditionTrue": true,
        "isTemplateResource": true,
        "location": "westus",
        "properties": {
          "containers": [
            {
              "name": "worker-container-0",
              "properties": {
                "environmentVariables": [],
                "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
                "instanceView": {
                  "currentState": {
                    "detailStatus": "",
                    "startTime": "2023-07-31T19:25:31.996Z",
                    "state": "Running"
                  },
                  "restartCount": 0
                },
                "ports": [
                  {
                    "port": 80,
                    "protocol": "TCP"
                  }
                ],
                "resources": {
                  "requests": {
                    "cpu": 1.0,
                    "memoryInGB": 2.0
                  }
                }
              }
            }
          ],
          "initContainers": [],
          "instanceView": {
            "events": [],
            "state": "Running"
          },
          "ipAddress": {
            "ip": "20.66.74.26",
            "ports": [
              {
                "port": 80,
                "protocol": "TCP"
              }
            ],
            "type": "Public"
          },
          "isCustomProvisioningTimeout": false,
          "osType": "Linux",
          "provisioningState": "Succeeded",
          "provisioningTimeoutInSeconds": 1800,
          "restartPolicy": "Always",
          "sku": "Standard"
        },
        "provisioningOperation": "Create",
        "references": [],
        "resourceGroupName": "demoRg",
        "resourceId": "Microsoft.ContainerInstance/containerGroups/worker-0",
        "scope": "",
        "subscriptionId": "",
        "symbolicName": "containerWorkers[0]"
      },
      ...
    ]
  },
  "containers": {
    "type": "Array",
    "value": [
      {
        "containers": [
          {
            "name": "worker-container-0",
            "properties": {
              "environmentVariables": [],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "instanceView": {
                "currentState": {
                  "detailStatus": "",
                  "startTime": "2023-07-31T19:25:31.996Z",
                  "state": "Running"
                },
                "restartCount": 0
              },
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1.0,
                  "memoryInGB": 2.0
                }
              }
            }
          }
        ],
        "initContainers": [],
        "instanceView": {
          "events": [],
          "state": "Running"
        },
        "ipAddress": {
          "ip": "20.66.74.26",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ],
          "type": "Public"
        },
        "isCustomProvisioningTimeout": false,
        "osType": "Linux",
        "provisioningState": "Succeeded",
        "provisioningTimeoutInSeconds": 1800,
        "restartPolicy": "Always",
        "sku": "Standard"
      },
      ...
    ]
  }
}

resourceGroup

Vea la función de ámbito resourceGroup.

En Bicep, use la función de ámbito resourceGroup.

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.

En Bicep, use la función resourceId.

Parámetros

Parámetro	Obligatorio	Type	Descripción
subscriptionId	No	Cadena (en formato de GUID)	El valor predeterminado es la suscripción actual. Especifique este valor cuando necesite recuperar un recurso en otra suscripción. Proporcione solo este valor al realizar la implementación en el ámbito de un grupo de recursos o suscripción.
resourceGroupName	No	string	El valor predeterminado es el grupo de recursos actual. Especifique este valor cuando necesite recuperar un recurso en otro grupo de recursos. Proporcione solo este valor al realizar la implementación en el ámbito de un grupo de recursos.
resourceType	Sí	string	Tipo de recurso, incluido el espacio de nombres del proveedor de recursos.
resourceName1	Sí	string	Nombre del recurso.
resourceName2	No	string	Segmento con el nombre del siguiente segmento, si es necesario.

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

Valor devuelto

El id. de recurso se devuelve en diferentes formatos en distintos ámbitos:

• Ámbito del grupo de recursos:

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

• Ámbito de la suscripción:

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

• Ámbito del grupo de administración o del inquilino:

  /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().
• Para los recursos de nivel de grupo de administración, use la función managementGroupResourceId. 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": "2022-11-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:

Nombre	Tipo	Value
sameRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput	String	/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

subscription

Vea la función de ámbito subscription.

En Bicep, use la función de ámbito subscription.

subscriptionResourceId

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

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

En Bicep, use la función subscriptionResourceId.

Parámetros

Parámetro	Obligatorio	Type	Descripción
subscriptionId	No	Cadena (en formato de GUID)	El valor predeterminado es la suscripción actual. Especifique este valor cuando necesite recuperar un recurso en otra suscripción.
resourceType	Sí	string	Tipo de recurso, incluido el espacio de nombres del proveedor de recursos.
resourceName1	Sí	string	Nombre del recurso.
resourceName2	No	string	Segmento con el nombre del siguiente segmento, si es necesario.

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": "2022-04-01",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

managementGroupResourceId

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

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

En Bicep, use la función managementGroupResourceId.

Parámetros

Parámetro	Obligatorio	Type	Descripción
managementGroupResourceId	No	Cadena (en formato de GUID)	El valor predeterminado es el grupo de administración actual. Especifique este valor cuando necesite recuperar un recurso en otro grupo de administración.
resourceType	Sí	string	Tipo de recurso, incluido el espacio de nombres del proveedor de recursos.
resourceName1	Sí	string	Nombre del recurso.
resourceName2	No	string	Segmento con el nombre del siguiente segmento, si es necesario.

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/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}

Observaciones

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

Ejemplo de managementGroupResourceID

La siguiente plantilla crea y asigna una definición de directiva. Usa la función managementGroupResourceId para obtener el id. de recurso de la definición de directiva.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "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."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2021-06-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    "location_lock": {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2022-06-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

tenantResourceId

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

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

En Bicep, use la función tenantResourceId.

Parámetros

Parámetro	Obligatorio	Type	Descripción
resourceType	Sí	string	Tipo de recurso, incluido el espacio de nombres del proveedor de recursos.
resourceName1	Sí	string	Nombre del recurso.
resourceName2	No	string	Segmento con el nombre del siguiente segmento, si es necesario.

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": "2022-06-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.