Funções para uso com Azure Blueprints

O Azure Blueprints fornece funções que tornam a definição de um blueprint mais dinâmica. Estas funções destinam-se a ser usadas com definições de blueprint e artefactos de blueprint. Um artefacto do Azure Resource Manager Template (template ARM) suporta a utilização completa das funções do Resource Manager, além de obter um valor dinâmico através de um parâmetro blueprint.

São suportadas as seguintes funções:

• artefatos
• concat
• parameters
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

Devolve um objeto de propriedades preenchido com esses artefactos do blueprint.

Parâmetros

Valor de retorno

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

{
  "outputs": {collectionOfOutputProperties}
}

Artefacto de atribuição de políticas

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

Artefacto do modelo ARM

As propriedades de saída do objeto devolvido são definidas dentro do template ARM e devolvidas pela implementação.

Artefacto de atribuição de papéis

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

Example

Um artefacto 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 da amostra myTemplateArtifact são:

concat

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

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

Parâmetros

Valor de retorno

Uma cadeia de valores concatenados.

Observações

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

Example

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

parameters

parameters(parameterName)

Devolve um valor do parâmetro blueprint. O nome do parâmetro especificado deve ser definido na definição do blueprint ou nos artefactos do blueprint.

Parâmetros

Valor de retorno

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

Observações

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

Example

Defina os principalIds 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() num artefacto 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()

Devolve um objeto que representa o grupo de recursos atual.

Valor de retorno

O objeto devolvido está no seguinte formato:

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

Observações

A função Azure Blueprints difere da função modelo ARM. A resourceGroup() função não pode ser usada num artefacto de nível de subscrição ou na definição do blueprint. Só pode ser usado em artefactos de blueprint que fazem parte de um artefacto de grupo de recursos.

Uma utilização comum da resourceGroup() função é criar recursos no mesmo local do artefacto do grupo de recursos.

Example

Para usar a localização do grupo de recursos, definida na definição do blueprint ou durante a atribuição, como local para outro artefacto, 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 artefacto de blueprint que esteja a direcionar um objeto marcador de grupo de recursos. Neste exemplo, o artefacto do template é implementado no grupo de recursos NetworkingPlaceholder e fornece o parâmetro resourceLocation preenchido dinamicamente com a localização do grupo de recursos NetworkingPlaceholder para o template. A localização do grupo de recursos NetworkingPlaceholder poderia ter sido definida estaticamente na definição do blueprint ou definida dinamicamente durante a atribuição. Em qualquer dos casos, o artefacto do modelo recebe essa informação como parâmetro e utiliza-a para posicionar os recursos no local correto.

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

resourceGroups

resourceGroups(placeholderName)

Devolve um objeto que representa o artefacto do grupo de recursos especificado. Ao contrário de , que requer contexto do artefacto, esta função é usada para obter as propriedades de um grupo de recursos específico como resourceGroup()marcador de posição quando não está no contexto desse grupo de recursos.

Parâmetros

Valor de retorno

O objeto devolvido está no seguinte formato:

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

Example

Para usar a localização do grupo de recursos, definida na definição do blueprint ou durante a atribuição, como local para outro artefacto, 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 usa a resourceGroups() função do contexto de qualquer artefacto de blueprint para obter uma referência ao objeto marcador do grupo de recursos. Neste exemplo, o artefacto do template é implementado fora do grupo de recursos NetworkingPlaceholder e fornece o artefacto do parâmetro Location, 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 definida dinamicamente durante a atribuição. Em qualquer dos casos, o artefacto do modelo recebe essa informação como parâmetro e utiliza-a para posicionar os recursos no local correto.

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

subscrição

subscription()

Devolve detalhes sobre a subscrição para a designação atual.

Valor de retorno

O objeto devolvido está no seguinte formato:

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

Example

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

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

Passos seguintes

• Saiba mais sobre o ciclo de vida do esquema.
• Entenda como usar parâmetros estáticos e dinâmicos.
• Aprenda a personalizar a ordem de sequenciação do esquema.
• Saiba como utilizar o bloqueio de recursos de esquema.
• Saiba como atualizar as atribuições existentes.
• Resolva problemas durante a atribuição de um esquema com resolução de problemas gerais.