Funções para uso com o Azure Blueprints

  • Artigo

Importante

Em 11 de julho de 2026, o Blueprints (versão prévia) será preterido. Migre suas definições e atribuições de blueprint existentes para Especificações de Modelo e Pilhas de Implantação. Os artefatos de blueprint devem ser convertidos em modelos JSON do ARM ou arquivos Bicep usados para definir pilhas de implantação. Para saber como criar um artefato como um recurso do ARM, confira:

O Azure Blueprints fornece funções que tornam uma definição de blueprint mais dinâmica. Essas funções são para uso com definições de blueprint e artefatos de blueprint. Um artefato do modelo do ARM (Modelo do Resource Manager do Azure) é compatível com o uso completo de funções do Resource Manager, além de obter um valor dinâmico por meio de um parâmetro de blueprint.

As seguintes funções não são compatíveis:

artifacts

artifacts(artifactName)

Retorna um objeto das propriedades preenchidas com as saídas dos artefatos de blueprint.

Observação

A função artifacts() não pode ser usada dentro de um Modelo do ARM. A função só pode ser usada no JSON da definição de blueprint ou no artefato JSON ao gerenciar o blueprint com o Azure PowerShell ou a API REST como parte de Blueprints como código.

Parâmetros

Parâmetro Obrigatório Type Descrição
artifactName Sim string O nome de um artefato de blueprint.

Valor retornado

Um objeto de propriedades de saída. As propriedades de saídas dependem do tipo de artefato de blueprint que está sendo referenciado. Todos os tipos seguem o formato:

{
  "outputs": {collectionOfOutputProperties}
}

Artefato de atribuição de política

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

Artefato de modelo do ARM

As propriedades de saídas do objeto retornado são definidas no modelo do ARM e retornadas pela implantação.

Artefato de atribuição de função

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

Exemplo

Um artefato do modelo do ARM com a ID myTemplateArtifact que contém a seguinte propriedade de saída de exemplo:

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

Alguns exemplos de recuperação de dados do exemplo myTemplateArtifact são:

Expression Type Valor
[artifacts("myTemplateArtifact").outputs.myArray] Array ["first", "second"]
[artifacts("myTemplateArtifact").outputs.myArray[0]] String "primeiro"
[artifacts("myTemplateArtifact").outputs.myString] String "meu valor de cadeia de caracteres"
[artifacts("myTemplateArtifact").outputs.myObject] Objeto { "myproperty": "my value", "anotherProperty": true }
[artifacts("myTemplateArtifact").outputs.myObject.myProperty] String "meu valor"
[artifacts("myTemplateArtifact").outputs.myObject.anotherProperty] Bool True

concat

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

Combina vários valores de cadeia de caracteres e retorna o resultado concatenado.

Parâmetros

Parâmetro Obrigatório Type Descrição
string1 Sim string O primeiro valor de concatenação.
argumentos adicionais Não string Valores adicionais em ordem sequencial para concatenação

Valor retornado

Uma cadeia de caracteres de valores concatenados.

Comentários

A função do Azure Blueprints difere da função do modelo do ARM, pois só funciona com cadeias de caracteres.

Exemplo

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

parâmetros

parameters(parameterName)

Retorna um valor de parâmetro de blueprint. O nome do parâmetro especificado deve ser definido na definição do blueprint ou em artefatos de blueprint.

Parâmetros

Parâmetro Obrigatório Type Descrição
parameterName Sim string O nome do parâmetro a retornar.

Valor retornado

O valor do parâmetro de artefato de blueprint ou do blueprint especificado.

Comentários

A função do Azure Blueprints difere da função do modelo do ARM, pois só funciona com parâmetros de blueprint.

Exemplo

Defina o parâmetro principalIds na definição do 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"
                }
            }
        },
        ...
    }
}

Em seguida, use o principalIds como o argumento para parameters() em um artefato de blueprint:

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

resourceGroup

resourceGroup()

Retorna um objeto que representa o grupo de recursos atual.

Valor retornado

O objeto retornado está no seguinte formato:

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

Comentários

A função do Azure Blueprints difere da função do modelo do ARM. A função resourceGroup() não pode ser usada em um artefato de nível de assinatura ou na definição do blueprint. Ela só pode ser usada em artefatos de blueprint que fazem parte de um artefato de grupo de recursos.

Um uso comum da função resourceGroup() é criar recursos na mesma localização que o artefato do grupo de recursos.

Exemplo

Para usar a localização do grupo de recursos, configure na definição do blueprint ou durante a atribuição, como a localização de outro artefato, declare um objeto de espaço reservado do grupo de recursos na definição do blueprint. Neste exemplo, NetworkingPlaceholder é o nome do espaço reservado do grupo de recursos.

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

Em seguida, use a função resourceGroup() no contexto de um artefato de blueprint destinado a um objeto de espaço reservado do grupo de recursos. Neste exemplo, o artefato do modelo é implantado no grupo de recursos NetworkingPlaceholder e fornece o parâmetro resourceLocation preenchido dinamicamente com a localização do grupo de recursos NetworkingPlaceholder para o modelo. A localização do grupo de recursos do NetworkingPlaceholder poderia ter sido estaticamente definido na definição do blueprint ou definido dinamicamente durante a atribuição. Em ambos os casos, o artefato do modelo recebe essas informações como um parâmetro e as usa para implantar os recursos na localização correta.

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

resourceGroups

resourceGroups(placeholderName)

Retorna um objeto que representa o artefato do grupo de recursos especificado. Ao contrário de resourceGroup(), que requer o contexto do artefato, essa função é usada para obter as propriedades de um espaço reservado de grupo de recursos específico quando não está no contexto desse grupo de recursos.

Parâmetros

Parâmetro Obrigatório Type Descrição
placeholderName Sim string O nome do espaço reservado do artefato do grupo de recursos a ser retornado.

Valor retornado

O objeto retornado está no seguinte formato:

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

Exemplo

Para usar a localização do grupo de recursos, configure na definição do blueprint ou durante a atribuição, como a localização de outro artefato, declare um objeto de espaço reservado do grupo de recursos na definição do blueprint. Neste exemplo, NetworkingPlaceholder é o nome do espaço reservado do grupo de recursos.

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

Em seguida, use a função resourceGroups() do contexto de qualquer artefato de blueprint para obter uma referência ao objeto do espaço reservado do grupo de recursos. Neste exemplo, o artefato do modelo é implantado fora do grupo de recursos NetworkingPlaceholder e fornece o parâmetro artifactLocation preenchido dinamicamente com a localização do grupo de recursos NetworkingPlaceholder para o modelo. A localização do grupo de recursos do NetworkingPlaceholder poderia ter sido estaticamente definido na definição do blueprint ou definido dinamicamente durante a atribuição. Em ambos os casos, o artefato do modelo recebe essas informações como um parâmetro e as usa para implantar os recursos na localização correta.

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

subscription

subscription()

Retorna detalhes sobre a assinatura da atribuição de blueprint atual.

Valor retornado

O objeto retornado está no seguinte formato:

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

Exemplo

Use o nome de exibição da assinatura e a função concat() para criar uma convenção de nomenclatura passada como parâmetro resourceName para o artefato do modelo.

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

Próximas etapas