Criação de plantas dinâmicas através de parâmetros
Importante
Em 11 de julho de 2026, os Blueprints (Preview) serão preteridos. Migre suas definições e atribuições de blueprint existentes para Especificações de modelo e Pilhas de implantação. Os artefatos do Blueprint devem ser convertidos em modelos JSON ARM ou arquivos Bicep usados para definir pilhas de implantação. Para saber como criar um artefato como um recurso ARM, consulte:
Um plano totalmente definido com vários artefatos, como grupos de recursos, modelos do Azure Resource Manager (modelos ARM), políticas ou atribuições de função, oferece a criação rápida e a criação consistente de objetos no Azure. Para permitir o uso flexível desses padrões de design e contêineres reutilizáveis, o Azure Blueprints dá suporte a parâmetros. O parâmetro cria flexibilidade, tanto durante a definição quanto a atribuição, para alterar as propriedades nos artefatos implantados pelo blueprint.
Um exemplo simples é o artefato do grupo de recursos. Quando um grupo de recursos é criado, ele tem dois valores necessários que devem ser fornecidos: nome e local. Ao adicionar um grupo de recursos ao seu blueprint, se os parâmetros não existissem, você definiria esse nome e local para cada uso do blueprint. Essa repetição faria com que cada uso do blueprint criasse artefatos no mesmo grupo de recursos. Os recursos dentro desse grupo de recursos se tornariam duplicados e causariam 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 em um blueprint, o blueprint continuará a criar os artefatos relacionados nesse grupo de recursos. Isso pode causar um conflito, pois dois recursos com o mesmo nome e tipo de recurso não podem existir em uma assinatura.
A solução para este problema são os parâmetros. Azure Blueprints permite definir o valor para cada propriedade do artefato durante a atribuição a uma assinatura. O parâmetro torna possível reutilizar um blueprint que cria um grupo de recursos e outros recursos dentro de uma única assinatura sem ter conflito.
Parâmetros de esquema
Através da API REST, os parâmetros podem ser criados no próprio blueprint. Esses parâmetros são diferentes dos parâmetros em cada um dos artefatos suportados. Quando um parâmetro é criado no blueprint, ele pode ser usado pelos artefatos nesse blueprint. Um exemplo pode ser o prefixo para nomear o grupo de recursos. O artefato pode usar o parâmetro blueprint para criar um parâmetro "principalmente dinâmico". Como o parâmetro também pode ser definido durante a atribuição, esse padrão permite uma consistência que pode aderir às regras de nomenclatura. Para conhecer as etapas, consulte Definição de parâmetros estáticos - parâmetro de nível de blueprint.
Usando parâmetros secureString e secureObject
Enquanto um artefato de modelo ARM dá suporte a parâmetros dos tipos secureString e secureObject, o Azure Blueprints exige que cada um esteja conectado a um Cofre de Chaves do Azure. Esta medida de segurança previne a prática insegura de armazenar segredos juntamente com o Plano e incentiva o emprego de padrões seguros. O Azure Blueprints dá suporte a essa medida de segurança, detetando a inclusão de qualquer parâmetro seguro em um artefato de modelo ARM. Em seguida, o serviço solicita durante a atribuição as seguintes propriedades do Cofre da Chave por parâmetro seguro detetado:
- ID do recurso Key Vault
- Nome secreto do Cofre da Chave
- Versão secreta do Key Vault
Se a atribuição do blueprint usar uma identidade gerenciada atribuída ao sistema, o Cofre da Chave referenciado deverá existir na mesma assinatura à qual a definição do blueprint foi atribuída.
Se a atribuição do blueprint usar uma identidade gerenciada atribuída pelo usuário, o Cofre da Chave referenciado pode existir em uma assinatura centralizada. A identidade gerenciada deve receber direitos apropriados no Cofre da Chave antes da atribuição do blueprint.
Importante
Em ambos os casos, o Cofre da Chave deve ter Habilitar acesso ao Azure Resource Manager para implantação de modelo configurado na página Políticas de acesso. Para obter instruções sobre como habilitar esse recurso, consulte Key Vault - Enable template deployment.
Para obter mais informações sobre o Cofre da Chave do Azure, consulte Visão geral do Cofre da Chave.
Tipos de parâmetros
Parâmetros estáticos
Um valor de parâmetro definido na definição de um blueprint é chamado de parâmetro estático, porque cada uso do blueprint implantará o artefato usando esse valor estático. No exemplo de grupo de recursos, embora não faça sentido para o nome do grupo de recursos, pode fazer sentido para o local. Em seguida, cada atribuição do blueprint criaria o grupo de recursos, seja qual for o nome durante a atribuição, no mesmo local. Essa flexibilidade permite que você seja seletivo no que você define como necessário versus o que pode ser alterado durante a atribuição.
Definição de parâmetros estáticos no portal
Selecione Todos os serviços no painel esquerdo. Procure e selecione Esquemas.
Selecione Definições do Blueprint na página à esquerda.
Selecione um esquema existente e, em seguida, selecione Editar plano OU selecione + Criar plano e preencha as informações na guia Noções básicas.
Selecione Avançar: Artefatos OU selecione a guia Artefatos .
Os artefatos adicionados ao blueprint que têm opções de parâmetro exibem X de parâmetros Y preenchidos na coluna Parâmetros . Selecione a linha de artefato para editar os parâmetros do artefato.
A página Editar artefato exibe opções de valor apropriadas ao artefato selecionado. Cada parâmetro no artefato tem um título, uma caixa de valor e uma caixa de seleção. Defina a caixa como desmarcada para torná-la um parâmetro estático. No exemplo a seguir, apenas Location é um parâmetro estático, pois está desmarcado e Resource Group Name está marcado.
Definindo 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 de nível de blueprint
Ao criar um blueprint através da API REST, é possível criar parâmetros de blueprint. Para fazer isso, use o seguinte URI DA API REST e o formato do corpo:
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 que um parâmetro de nível de blueprint é criado, ele pode ser usado em artefatos adicionados a esse blueprint. O exemplo de API REST a seguir cria um artefato de atribuição de função no blueprint e usa o parâmetro de nível de blueprint.
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 usa o parâmetro owners blueprint level usando um valor de [parameters('owners')]
. Definir um parâmetro em um artefato usando um parâmetro de nível de blueprint ainda é um exemplo de um parâmetro estático. O parâmetro de nível de blueprint não pode ser definido durante a atribuição de blueprint e será o mesmo valor em cada atribuição.
Parâmetro de nível de artefato
Criar parâmetros estáticos em um artefato é semelhante, mas usa um valor reto em vez de usar a parameters()
função. O exemplo a seguir cria dois parâmetros estáticos, tagName e tagValue. O valor em cada um é fornecido diretamente e não usa 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 é definido no blueprint, mas é definido durante cada atribuição do blueprint. No exemplo de grupo de recursos, o uso de um parâmetro dinâmico faz sentido para o nome do grupo de recursos. Ele fornece um nome diferente para cada atribuição do projeto. Para obter uma lista de funções do blueprint, consulte a referência de funções do blueprint.
Definição de parâmetros dinâmicos no portal
Selecione Todos os serviços no painel esquerdo. Procure e selecione Esquemas.
Selecione Definições do Blueprint na página à esquerda.
Clique com o botão direito do rato no esquema que pretende atribuir. Selecione Atribuir blueprint OU selecione o blueprint que deseja atribuir e use o botão Atribuir blueprint .
Na página Atribuir blueprint, localize a seção Parâmetros de artefato. Cada artefato com pelo menos um parâmetro dinâmico exibe o artefato e as opções de configuração. Forneça os valores necessários para os parâmetros antes de atribuir o blueprint. No exemplo a seguir, Name é um parâmetro dinâmico que deve ser definido para concluir a atribuição do blueprint.
Definindo parâmetros dinâmicos a partir da API REST
A definição de parâmetros dinâmicos durante a atribuição é feita inserindo o valor diretamente. Em vez de usar uma função, como parameters(), o valor fornecido é uma cadeia de caracteres apropriada. Os artefatos para um grupo de recursos são definidos com um "nome do modelo", nome e propriedades de local . Todos os outros parâmetros para o artefato incluído são definidos em parâmetros com um par de <chaves de nome> e valor. Se o blueprint 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" }
Próximos passos
- Veja a lista de funções do blueprint.
- 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.