Funciones para su uso con Azure Blueprints

Azure Blueprints proporciona funciones que hacen que la definición de un blueprint sea más dinámica. Estas funciones son para usarse con definiciones de planos y artefactos de planos. Un artefacto de Azure Resource Manager Template (plantilla ARM) soporta el uso completo de funciones de Resource Manager además de obtener un valor dinámico a través de un parámetro blueprint.

Se admiten las siguientes funciones:

• artefactos
• concat
• Parámetros
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

Devuelve un objeto de propiedades poblado con ese artefacto de blueprint.

Parámetros

Valor devuelto

Un objeto de propiedades de salida. Las propiedades de las salidas dependen del tipo de artefacto de plano al que se referencia. Todos los tipos siguen el formato:

{
  "outputs": {collectionOfOutputProperties}
}

Artefacto de asignación de políticas

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

Artefacto de plantilla ARM

Las propiedades de salida del objeto devuelto se definen dentro de la plantilla ARM y se devuelven por el despliegue.

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 ARM con el ID myTemplateArtifact que contiene 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 muestra myTemplateArtifact son:

concat

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

Combina varios valores de cadena y devuelve la cadena concatenada.

Parámetros

Valor devuelto

Una cadena de valores concatenados.

Observaciones

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

Ejemplo

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

parameters

parameters(parameterName)

Devuelve un valor del parámetro blueprint. El nombre del parámetro especificado debe definirse en la definición del blueprint o en los artefactos del blueprint.

Parámetros

Valor devuelto

El valor del plano especificado o del parámetro artefacto del plano.

Observaciones

La función Azure Blueprints se diferencia de la función plantilla ARM en que solo funciona con parámetros de blueprint.

Ejemplo

Define los principalIds del parámetro en la definición del blueprint:

{
    "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"
                }
            }
        },
        ...
    }
}

Luego usa principalIds como argumento para parameters() en un artefacto de plano:

{
    "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 siguiente formato:

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

Observaciones

La función Azure Blueprints difiere de la función plantilla ARM. La resourceGroup() función no puede usarse en un artefacto de nivel de suscripción ni en la definición de blueprint. Solo puede usarse en artefactos de planos que forman parte de un artefacto de grupo de recursos.

Un uso común de la resourceGroup() función es crear recursos en la misma ubicación que el artefacto del grupo de recursos.

Ejemplo

Para usar la ubicación del grupo de recursos, establecida en la definición de blueprint o durante la asignación, como ubicación para otro artefacto, declara un objeto marcador de grupo de recursos en la definición de blueprint. En este ejemplo, NetworkingPlaceholder es el nombre del placeholder del grupo de recursos.

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

Luego utiliza la resourceGroup() función en el contexto de un artefacto de blueprint que está dirigido a un objeto marcador de grupo de recursos. En este ejemplo, el artefacto de la plantilla se despliega en el grupo de recursos NetworkingPlaceholder y proporciona el parámetro resourceLocation rellenado dinámicamente con la ubicación del grupo de recursos NetworkingPlaceholder a la plantilla. La ubicación del grupo de recursos NetworkingPlaceholder podría haberse definido estáticamente en la definición del blueprint o dinámicamente durante la asignación. En cualquier caso, el artefacto de la plantilla recibe esa información como parámetro y la utiliza para desplegar 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 especificado del grupo de recursos. A diferencia de , que requiere el contexto del artefacto, esta función se utiliza para obtener las propiedades de un grupo de recursos específico como resourceGroup()marcador de posición cuando no está en el contexto de ese grupo de recursos.

Parámetros

Valor devuelto

El objeto devuelto está en el siguiente formato:

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

Ejemplo

Para usar la ubicación del grupo de recursos, establecida en la definición de blueprint o durante la asignación, como ubicación para otro artefacto, declara un objeto marcador de grupo de recursos en la definición de blueprint. En este ejemplo, NetworkingPlaceholder es el nombre del placeholder del grupo de recursos.

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

Luego usa la resourceGroups() función desde el contexto de cualquier artefacto de plano para obtener una referencia al objeto marcador del grupo de recursos. En este ejemplo, el artefacto de la plantilla se despliega fuera del grupo de recursos NetworkingPlaceholder y proporciona el artefacto de parámetros Ubicación llenado dinámicamente con la ubicación del grupo de recursos NetworkingPlaceholder a la plantilla. La ubicación del grupo de recursos NetworkingPlaceholder podría haberse definido estáticamente en la definición del blueprint o dinámicamente durante la asignación. En cualquier caso, el artefacto de la plantilla recibe esa información como parámetro y la utiliza para desplegar 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()

Devolve detalles sobre la suscripción para la asignación actual del plano.

Valor devuelto

El objeto devuelto está en el siguiente formato:

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

Ejemplo

Utiliza el nombre de visualización de la suscripción y la concat() función para crear una convención de nombres que se pasa como 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

• Obtenga información sobre el ciclo de vida del plano técnico.
• Comprenda cómo usar parámetros estáticos y dinámicos.
• Aprenda a personalizar el orden de secuenciación del plano técnico.
• Obtenga información sobre cómo utilizar el bloqueo de recursos de blueprint.
• Obtenga información sobre cómo actualizar las asignaciones existentes.
• Resuelva los problemas durante la asignación de un diseño con la resolución de problemas general.