Funciones para usar con Azure Blueprints

Artículo
09/22/2023

Importante

El 11 de julio de 2026, Blueprints (versión preliminar) quedará en desuso. Migre las definiciones y asignaciones de planos técnicos existentes a Especificaciones de plantilla y Pilas de implementación. Los artefactos de plano técnico se convertirán en plantillas JSON de ARM o archivos de Bicep que se usan para definir pilas de implementación. Para obtener información sobre cómo crear un artefacto como un recurso de ARM, consulte:

Azure Blueprints proporciona funciones que aportan dinamismo a la definición de los planos técnicos. Estas funciones se usan con las definiciones y los artefactos de los planos técnicos. Un artefacto de la plantilla de Azure Resource Manager (plantilla de ARM) admite el uso completo de las funciones de Resource Manager, además de obtener un valor dinámico mediante un parámetro de plano técnico.

Se admiten las siguientes funciones:

artifacts
concat
parameters
resourceGroup
resourceGroups
suscripción

artifacts

artifacts(artifactName)

Devuelve un objeto de propiedades rellenadas con los resultados de los artefactos de ese plano técnico.

Nota

No se puede usar la función artifacts() desde dentro de una plantilla de ARM. La función solo se puede usar en el JSON de definición de plano técnico o en el JSON del artefacto al administrar el plano técnico con Azure PowerShell o la API REST como parte de planos técnicos como código.

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
artifactName	Sí	string	El nombre de un artefacto de plano técnico.

Valor devuelto

Un objeto de propiedades de salida. Las propiedades outputs dependen del tipo de artefacto de plano técnico al que se hace referencia. Todos los tipos tienen este formato:

{
  "outputs": {collectionOfOutputProperties}
}

Artefacto de la asignación de directiva

{
    "outputs": {
        "policyAssignmentId": "{resourceId-of-policy-assignment}",
        "policyAssignmentName": "{name-of-policy-assignment}",
        "policyDefinitionId": "{resourceId-of-policy-definition}",
    }
}

Artefacto de plantilla de ARM

Las propiedades outputs del objeto devuelto se definen en la plantilla de ARM y las devuelve la implementación.

Artefacto de asignación de roles

{
    "outputs": {
        "roleAssignmentId": "{resourceId-of-role-assignment}",
        "roleDefinitionId": "{resourceId-of-role-definition}",
        "principalId": "{principalId-role-is-being-assigned-to}",
    }
}

Ejemplo

Un artefacto de plantilla de ARM con el identificador myTemplateArtifact que contenga la siguiente propiedad de salida de ejemplo:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    ...
    "outputs": {
        "myArray": {
            "type": "array",
            "value": ["first", "second"]
        },
        "myString": {
            "type": "string",
            "value": "my string value"
        },
        "myObject": {
            "type": "object",
            "value": {
                "myProperty": "my value",
                "anotherProperty": true
            }
        }
    }
}

Algunos ejemplos de recuperación de datos de la plantilla myTemplateArtifact son los siguientes:

Expression	Tipo	Value
`[artifacts("myTemplateArtifact").outputs.myArray]`	Array	["first", "second"]
`[artifacts("myTemplateArtifact").outputs.myArray[0]]`	String	"first"
`[artifacts("myTemplateArtifact").outputs.myString]`	String	"my string value"
`[artifacts("myTemplateArtifact").outputs.myObject]`	Object	{ "myproperty": "my value", "anotherProperty": true }
`[artifacts("myTemplateArtifact").outputs.myObject.myProperty]`	String	"my value"
`[artifacts("myTemplateArtifact").outputs.myObject.anotherProperty]`	Bool	True

concat

concat(string1, string2, string3, ...)

Combina varios valores de cadena y devuelve la cadena concatenada.

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
string1	Sí	string	El primer valor para la concatenación.
argumentos adicionales	No	string	Valores adicionales en orden secuencial para la concatenación

Valor devuelto

Una cadena de valores concatenados.

Observaciones

La función Azure Blueprints difiere de la función de plantilla de ARM en que solo admite cadenas.

Ejemplo

concat(parameters('organizationName'), '-vm')

parámetros

parameters(parameterName)

Devuelve un valor de parámetro de plano técnico. El nombre del parámetro especificado debe estar definido en la definición o en los artefactos del plano técnico.

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
parameterName	Sí	string	El nombre del parámetro que se va a devolver.

Valor devuelto

El valor del parámetro del plano técnico o del artefacto de plano técnico especificado.

Observaciones

La función Azure Blueprints difiere de la función de la plantilla de ARM en que solo admite parámetros de plano técnico.

Ejemplo

Defina el parámetro principalIds en la definición del plano técnico:

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "parameters": {
            "principalIds": {
                "type": "array",
                "metadata": {
                    "displayName": "Principal IDs",
                    "description": "This is a blueprint parameter that any artifact can reference. We'll display these descriptions for you in the info bubble. Supply principal IDs for the users,groups, or service principals for the Azure role assignment.",
                    "strongType": "PrincipalId"
                }
            }
        },
        ...
    }
}

Después use principalIds como argumento para parameters() en un artefacto de plano técnico:

{
    "type": "Microsoft.Blueprint/blueprints/artifacts",
    "kind": "roleAssignment",
    ...
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('principalIds')]",
        ...
    }
}

resourceGroup

resourceGroup()

Devuelve un objeto que representa el grupo de recursos actual.

Valor devuelto

El objeto devuelto está en el formato siguiente:

{
  "name": "{resourceGroupName}",
  "location": "{resourceGroupLocation}",
}

Observaciones

La función Azure Blueprints difiere de la función de la plantilla de ARM. La función resourceGroup() no se puede usar en un artefacto de nivel de suscripción ni en la definición del plano técnico. Solo puede usarse en artefactos de plano técnico que forman parte de un artefacto del grupo de recursos.

La función resourceGroup() acostumbra a usarse para crear recursos en la misma ubicación que artefacto del grupo de recursos.

Ejemplo

Para usar como ubicación de otro artefacto la ubicación del grupo de recursos, establecida en la definición del plano técnico o durante la asignación, indique un objeto de marcador de posición del grupo de recursos en la definición del plano técnico. En este ejemplo, NetworkingPlaceholder es el nombre del marcador de posición del grupo de recursos.

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "resourceGroups": {
            "NetworkingPlaceholder": {
                "location": "eastus"
            }
        }
    }
}

Después utilice la función resourceGroup() en el contexto de un artefacto de plano técnico destinado a un objeto de marcador de posición de grupo de recursos. En este ejemplo, el artefacto de la plantilla se implementa en el grupo de recursos NetworkingPlaceholder y proporciona el parámetro resourceLocation que se rellena dinámicamente con la ubicación del grupo de recursos NetworkingPlaceholder en la plantilla. La ubicación del grupo de recursos NetworkingPlaceholder puede haberse definido estáticamente en la definición del plano técnico o dinámicamente durante la asignación. En cualquier caso, el artefacto de la plantilla recibe esa información como un parámetro y lo usa para implementar los recursos en la ubicación correcta.

{
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "kind": "template",
  "properties": {
      "template": {
        ...
      },
      "resourceGroup": "NetworkingPlaceholder",
      ...
      "parameters": {
        "resourceLocation": {
          "value": "[resourceGroup().location]"
        }
      }
  }
}

resourceGroups

resourceGroups(placeholderName)

Devuelve un objeto que representa el artefacto del grupo de recursos especificado. A diferencia de resourceGroup(), que requiere el contexto del artefacto, esta función se utiliza para obtener las propiedades de un marcador de posición de grupo de recursos específico cuando no esté en el contexto de ese grupo de recursos.

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
placeholderName	Sí	string	El nombre de marcador de posición del artefacto del grupo de recursos que se va a devolver.

Valor devuelto

El objeto devuelto está en el formato siguiente:

{
  "name": "{resourceGroupName}",
  "location": "{resourceGroupLocation}",
}

Ejemplo

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "resourceGroups": {
            "NetworkingPlaceholder": {
                "location": "eastus"
            }
        }
    }
}

Después utilice la función resourceGroups() en el contexto de un artefacto de plano técnico para obtener una referencia al objeto de marcador de posición de grupo de recursos. En este ejemplo, el artefacto de la plantilla se implementa fuera del grupo de recursos NetworkingPlaceholder y proporciona el parámetro artifactLocation que se rellena dinámicamente con la ubicación del grupo de recursos NetworkingPlaceholder en la plantilla. La ubicación del grupo de recursos NetworkingPlaceholder puede haberse definido estáticamente en la definición del plano técnico o dinámicamente durante la asignación. En cualquier caso, el artefacto de la plantilla recibe esa información como un parámetro y lo usa para implementar los recursos en la ubicación correcta.

{
  "kind": "template",
  "properties": {
      "template": {
          ...
      },
      ...
      "parameters": {
        "artifactLocation": {
          "value": "[resourceGroups('NetworkingPlaceholder').location]"
        }
      }
  },
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "name": "myTemplate"
}

subscription

subscription()

Devuelve detalles sobre la suscripción para la asignación actual del plano técnico.

Valor devuelto

El objeto devuelto está en el formato siguiente:

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

Ejemplo

Utilice el nombre para mostrar de la suscripción y la función concat() para crear una convención de nomenclatura que pasa como el parámetro resourceName al artefacto de la plantilla.

{
  "kind": "template",
  "properties": {
      "template": {
          ...
      },
      ...
      "parameters": {
        "resourceName": {
          "value": "[concat(subscription().displayName, '-vm')]"
        }
      }
  },
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "name": "myTemplate"
}

Pasos siguientes

Información acerca del ciclo de vida del plano técnico.
Descubra cómo utilizar parámetros estáticos y dinámicos.
Aprenda a personalizar el orden de secuenciación de planos técnicos.
Averigüe cómo usar el bloqueo de recursos de planos técnicos.
Aprenda a actualizar las asignaciones existentes.
Puede consultar la información de solución de problemas generales para resolver los problemas durante la asignación de un plano técnico.

Funciones para usar con Azure Blueprints

artifacts

Parámetros

Valor devuelto

Artefacto de la asignación de directiva

Artefacto de plantilla de ARM

Artefacto de asignación de roles

Ejemplo

concat

Parámetros

Valor devuelto

Observaciones

Ejemplo

parámetros

Parámetros

Valor devuelto

Observaciones

Ejemplo

resourceGroup

Valor devuelto

Observaciones

Ejemplo

resourceGroups

Parámetros

Valor devuelto

Ejemplo

subscription

Valor devuelto

Ejemplo

Pasos siguientes

Recursos adicionales