Funções para uso com o Azure Blueprints

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
• concat
• parameters
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

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

Parâmetros

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:

concat

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

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

Parâmetros

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

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

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

• Saiba mais sobre o ciclo de vida do blueprint.
• Saiba como usar parâmetros estáticos e dinâmicos.
• Saiba como personalizar a ordem de sequenciamento de blueprint.
• Saiba como usar o bloqueio de recurso de blueprint.
• Saiba como atualizar atribuições existentes.
• Resolver problemas durante a atribuição de blueprint com solução de problemas gerais.