Criar esquemas dinâmicos através de parâmetros

Artigo
09/07/2023

Importante

A 11 de julho de 2026, o Blueprints (Pré-visualização) será preterido. Migre as definições e atribuições de esquemas existentes para Especificações de Modelo e Pilhas de Implementação. Os artefactos de esquema devem ser convertidos em modelos JSON do ARM ou ficheiros Bicep utilizados para definir pilhas de implementação. Para saber como criar um artefacto como um recurso do ARM, veja:

Um esquema totalmente definido com vários artefactos, como grupos de recursos, modelos do Azure Resource Manager (modelos arm), políticas ou atribuições de funções, oferece a criação rápida e a criação consistente de objetos no Azure. Para permitir a utilização flexível destes contentores e padrões de estrutura reutilizáveis, o Azure Blueprints suporta parâmetros. O parâmetro cria flexibilidade, tanto durante a definição como a atribuição, para alterar as propriedades nos artefactos implementados pelo esquema.

Um exemplo simples é o artefacto do grupo de recursos. Quando um grupo de recursos é criado, tem dois valores necessários que têm de ser fornecidos: nome e localização. Ao adicionar um grupo de recursos ao seu esquema, se os parâmetros não existissem, definiria esse nome e localização para cada utilização do esquema. Esta repetição faria com que todas as utilizações do esquema criassem artefactos no mesmo grupo de recursos. Os recursos dentro desse grupo de recursos tornar-se-iam duplicados e provocariam um conflito.

Nota

Não é um problema para dois esquemas diferentes incluir um grupo de recursos com o mesmo nome. Se já existir um grupo de recursos incluído num esquema, o esquema continua a criar os artefactos relacionados nesse grupo de recursos. Isto pode causar um conflito, uma vez que dois recursos com o mesmo nome e tipo de recurso não podem existir numa subscrição.

A solução para este problema são os parâmetros. O Azure Blueprints permite-lhe definir o valor para cada propriedade do artefacto durante a atribuição a uma subscrição. O parâmetro permite reutilizar um esquema que cria um grupo de recursos e outros recursos numa única subscrição sem ter conflitos.

Parâmetros de esquema

Através da API REST, os parâmetros podem ser criados no próprio esquema. Estes parâmetros são diferentes dos parâmetros em cada um dos artefactos suportados. Quando um parâmetro é criado no esquema, pode ser utilizado pelos artefactos nesse esquema. Um exemplo pode ser o prefixo para a nomenclatura do grupo de recursos. O artefacto pode utilizar o parâmetro de esquema para criar um parâmetro "maioritariamente dinâmico". Como o parâmetro também pode ser definido durante a atribuição, este padrão permite uma consistência que pode cumprir as regras de nomenclatura. Para obter os passos, veja Definir parâmetros estáticos – parâmetro ao nível do esquema.

Utilizar os parâmetros secureString e secureObject

Embora um artefacto de modelo arm suporte parâmetros dos tipos secureString e secureObject, o Azure Blueprints requer que cada um esteja ligado a um Key Vault do Azure. Esta medida de segurança impede a prática insegura de armazenar segredos juntamente com o Blueprint e incentiva o emprego de padrões seguros. O Azure Blueprints suporta esta medida de segurança, detetando a inclusão de qualquer parâmetro seguro num artefacto de modelo do ARM. Em seguida, o serviço pede durante a atribuição as seguintes propriedades de Key Vault por parâmetro seguro detetado:

ID do recurso Key Vault
Key Vault nome do segredo
Key Vault versão secreta

Se a atribuição do esquema utilizar uma identidade gerida atribuída pelo sistema, o Key Vault referenciado tem de existir na mesma subscrição à qual a definição do esquema está atribuída.

Se a atribuição do esquema utilizar uma identidade gerida atribuída pelo utilizador, o Key Vault referenciado poderá existir numa subscrição centralizada. A identidade gerida tem de ter direitos adequados no Key Vault antes da atribuição do esquema.

Importante

Em ambos os casos, o Key Vault tem de ter Ativar o acesso ao Azure Resource Manager para implementação de modelos configurado na página Políticas de acesso. Para obter instruções sobre como ativar esta funcionalidade, veja Key Vault – Ativar a implementação de modelos.

Para obter mais informações sobre o Azure Key Vault, veja Descrição Geral do Key Vault.

Tipos de parâmetros

Parâmetros estáticos

Um valor de parâmetro definido na definição de um esquema é denominado parâmetro estático, porque cada utilização do esquema implementará o artefacto com esse valor estático. No exemplo do grupo de recursos, embora não faça sentido para o nome do grupo de recursos, poderá fazer sentido para a localização. Em seguida, cada atribuição do esquema criaria o grupo de recursos, o que quer que seja chamado durante a atribuição, na mesma localização. Esta flexibilidade permite-lhe ser seletivo naquilo que define como necessário vs. o que pode ser alterado durante a atribuição.

Definir parâmetros estáticos no portal

Selecione Todos os serviços no painel esquerdo. Procure e selecione Esquemas.
Selecione Definições de esquema na página à esquerda.
Selecione um esquema existente e, em seguida, selecione Editar esquema OU selecione + Criar esquema e preencha as informações no separador Noções básicas .
Selecione Seguinte: Artefactos OU selecione o separador Artefactos .
Os artefactos adicionados ao esquema que têm opções de parâmetros apresentam parâmetros X de Y preenchidos na coluna Parâmetros . Selecione a linha do artefacto para editar os parâmetros do artefacto.
A página Editar Artefacto apresenta as opções de valor adequadas ao artefacto selecionado. Cada parâmetro no artefacto tem um título, uma caixa de valor e uma caixa de verificação. Defina a caixa como desmarcada para torná-la um parâmetro estático. No exemplo seguinte, apenas a Localização é um parâmetro estático , uma vez que está desmarcado e o Nome do Grupo de Recursos está selecionado.

Definir parâmetros estáticos da API REST

Em cada URI da API REST, existem variáveis que são utilizadas que precisa de substituir pelos seus próprios valores:

{YourMG} - substituir pelo nome do seu grupo de gestão
{subscriptionId} - substituir pelo ID da subscrição

Parâmetro ao nível do esquema

Ao criar um esquema através da API REST, é possível criar parâmetros de esquema. Para tal, utilize o seguinte formato de corpo e URI da API REST:

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Corpo do Pedido

{
    "properties": {
        "description": "This blueprint has blueprint level parameters.",
        "targetScope": "subscription",
        "parameters": {
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

Depois de criar um parâmetro ao nível do esquema, pode ser utilizado em artefactos adicionados a esse esquema. O exemplo seguinte da API REST cria um artefacto de atribuição de função no esquema e utiliza o parâmetro ao nível do esquema.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleOwner?api-version=2018-11-01-preview

Corpo do Pedido

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

Neste exemplo, a propriedade principalIds utiliza o parâmetro de nível de esquema proprietários com um valor de [parameters('owners')]. Definir um parâmetro num artefacto com um parâmetro de nível de esquema ainda é um exemplo de um parâmetro estático. O parâmetro ao nível do esquema não pode ser definido durante a atribuição do esquema e será o mesmo valor em cada atribuição.

Parâmetro de nível de artefacto

Criar parâmetros estáticos num artefacto é semelhante, mas assume um valor reto em vez de utilizar a parameters() função. O exemplo seguinte cria dois parâmetros estáticos, tagName e tagValue. O valor em cada um é fornecido diretamente e não utiliza uma chamada de função.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyStorageTags?api-version=2018-11-01-preview

Corpo do Pedido

{
    "kind": "policyAssignment",
    "properties": {
        "description": "Apply storage tag and the parameter also used by the template to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "StorageType"
            },
            "tagValue": {
                "value": "Premium_LRS"
            }
        }
    }
}

Parâmetros dinâmicos

O oposto de um parâmetro estático é um parâmetro dinâmico. Este parâmetro não está definido no esquema, mas é definido durante cada atribuição do esquema. No exemplo do grupo de recursos, a utilização de um parâmetro dinâmico faz sentido para o nome do grupo de recursos. Fornece um nome diferente para cada atribuição do esquema. Para obter uma lista de funções de esquema, veja a referência de funções de esquema .

Definir parâmetros dinâmicos no portal

Selecione Todos os serviços no painel esquerdo. Procure e selecione Esquemas.
Selecione Definições de esquema na página à esquerda.
Clique com o botão direito do rato no esquema que pretende atribuir. Selecione Atribuir esquema OU selecione o esquema que pretende atribuir e, em seguida, utilize o botão Atribuir esquema .
Na página Atribuir esquema , localize a secção Parâmetros do artefacto . Cada artefacto com, pelo menos, um parâmetro dinâmico apresenta o artefacto e as opções de configuração. Forneça os valores necessários aos parâmetros antes de atribuir o esquema. No exemplo seguinte, Nome é um parâmetro dinâmico que tem de ser definido para concluir a atribuição de esquema.

Definir parâmetros dinâmicos a partir da API REST

A definição de parâmetros dinâmicos durante a atribuição é efetuada ao introduzir o valor diretamente. Em vez de utilizar uma função, como parâmetros(), o valor fornecido é uma cadeia adequada. Os artefactos de um grupo de recursos são definidos com um "nome de modelo", nome e propriedades de localização . Todos os outros parâmetros do artefacto incluído são definidos em parâmetros com um <par de chaves de nome> e valor . Se o esquema estiver configurado para um parâmetro dinâmico que não é fornecido durante a atribuição, a atribuição falhará.

URI da API REST

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Corpo do Pedido

{
    "properties": {
        "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}  /providers/Microsoft.Blueprint/blueprints/MyBlueprint",
        "resourceGroups": {
            "storageRG": {
                "name": "StorageAccount",
                "location": "eastus2"
            }
        },
        "parameters": {
            "storageAccountType": {
                "value": "Standard_GRS"
            },
            "tagName": {
                "value": "CostCenter"
            },
            "tagValue": {
                "value": "ContosoIT"
            },
            "contributors": {
                "value": [
                    "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
                    "38833b56-194d-420b-90ce-cff578296714"
                ]
              },
            "owners": {
                "value": [
                    "44254d2b-a0c7-405f-959c-f829ee31c2e7",
                    "316deb5f-7187-4512-9dd4-21e7798b0ef9"
                ]
            }
        }
    },
    "identity": {
        "type": "systemAssigned"
    },
    "location": "westus"
}

Passos seguintes

Veja a lista de funções de esquema.
Saiba mais sobre o ciclo de vida do esquema.
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 a resolução de problemas gerais.

Criar esquemas dinâmicos através de parâmetros

Parâmetros de esquema

Utilizar os parâmetros secureString e secureObject

Tipos de parâmetros

Parâmetros estáticos

Definir parâmetros estáticos no portal

Definir parâmetros estáticos da API REST

Parâmetro ao nível do esquema

Parâmetro de nível de artefacto

Parâmetros dinâmicos

Definir parâmetros dinâmicos no portal

Definir parâmetros dinâmicos a partir da API REST

Passos seguintes

Recursos adicionais