Funções para uso com Azure Blueprints

O Azure Blueprints fornece funções que tornam a 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 Azure Resource Manager Template (template ARM) suporta o uso completo das funções do Resource Manager, além de obter um valor dinâmico por meio de um parâmetro blueprint.

São suportadas as seguintes funções:

• artefatos
• concat
• Parâmetros
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

Retorna um objeto de propriedades preenchido com os artefatos do blueprint que gera.

Parâmetros

Valor de retorno

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

{
  "outputs": {collectionOfOutputProperties}
}

Artefato de atribuição de políticas

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

Artefato do modelo ARM

As propriedades de saída do objeto retornado são definidas dentro do template 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 de template ARM com o ID myTemplateArtifact contendo 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:

concat

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

Combina múltiplos valores de cadeia e retorna a cadeia concatenada.

Parâmetros

Valor de retorno

Uma sequência de valores concatenados.

Comentários

A função Azure Blueprints difere da função template ARM porque só funciona com strings.

Exemplo

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

parâmetros

parameters(parameterName)

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

Parâmetros

Valor de retorno

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

Comentários

A função Azure Blueprints difere da função template ARM porque funciona apenas com parâmetros de blueprint.

Exemplo

Defina os princípioIds do parâmetro 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"
                }
            }
        },
        ...
    }
}

Depois, use principalIds como argumento para parameters() 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 de retorno

O objeto retornado está no seguinte formato:

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

Comentários

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

Um uso comum da resourceGroup() função é criar recursos no mesmo local do artefato do grupo de recursos.

Exemplo

Para usar a localização do grupo de recursos, definida na definição do blueprint ou durante a atribuição, como local para outro artefato, declare um objeto placeholder do grupo de recursos na definição do seu blueprint. Neste exemplo, NetworkingPlaceholder é o nome do placeholder do grupo de recursos.

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

Depois, use a resourceGroup() função no contexto de um artefato de blueprint que está mirando um objeto provisório de grupo de recursos. Neste exemplo, o artefato do template é implantado no grupo de recursos NetworkingPlaceholder e fornece o parâmetro resourceLocation preenchido dinamicamente com a localização do grupo de recursos NetworkingPlaceholder ao template. A localização do grupo de recursos NetworkingPlaceholder poderia ter sido definida estaticamente na definição do blueprint ou dinamicamente durante a atribuição. Em ambos os casos, o artefato do modelo recebe essa informação como um parâmetro e a utiliza para implantar os recursos no local correto.

{
  "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 especificado do grupo de recursos. Diferente de , que requer contexto do artefato, essa função é usada para obter as propriedades de um grupo específico de recursos como resourceGroup()marcador quando não está no contexto desse grupo de recursos.

Parâmetros

Valor de retorno

O objeto retornado está no seguinte formato:

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

Exemplo

Para usar a localização do grupo de recursos, definida na definição do blueprint ou durante a atribuição, como local para outro artefato, declare um objeto placeholder do grupo de recursos na definição do seu blueprint. Neste exemplo, NetworkingPlaceholder é o nome do placeholder do grupo de recursos.

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

Depois, use a resourceGroups() função do contexto de qualquer artefato de blueprint para obter uma referência ao objeto placeholder do grupo de recursos. Neste exemplo, o artefato do template é implantado fora do grupo de recursos NetworkingPlaceholder e fornece o artefactoLocalização do parâmetro preenchido dinamicamente com a localização do grupo de recursos NetworkingPlaceholder para o modelo. A localização do grupo de recursos NetworkingPlaceholder poderia ter sido definida estaticamente na definição do blueprint ou dinamicamente durante a atribuição. Em ambos os casos, o artefato do modelo recebe essa informação como um parâmetro e a utiliza para implantar os recursos no local correto.

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

assinatura

subscription()

Retorna detalhes sobre a assinatura para a designação atual do projeto.

Valor de retorno

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 concat() função 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 

• Saiba mais sobre o ciclo de vida do blueprint.
• Entenda como usar parâmetros estáticos e dinâmicos.
• Saiba como personalizar a ordem de sequenciamento do blueprint.
• Descubra como usar o bloqueio de recursos do plano.
• Saiba como atualizar as atribuições existentes.
• Resolva problemas durante a atribuição de um modelo com diagnóstico geral.