Operação de e-se do bicep

Antes de implementar um ficheiro Bicep, pode pré-visualizar as alterações que irão ocorrer. O Gestor de Recursos do Azure fornece a operação de e-se para lhe permitir ver como os recursos serão alterados se implementar o ficheiro Bicep. A operação de e-se não fizer alterações aos recursos existentes. Em vez disso, prevê as alterações se o ficheiro Bicep especificado estiver implementado.

Pode utilizar a operação de what-if com as operações Azure PowerShell, Azure CLI ou REST API. O que fazer é suportado para implementar ao nível do grupo de recursos, subscrição, grupo de gestão e nível de inquilino.

Microsoft Learn

Se preferir saber mais sobre a operação de what-if através da orientação passo a passo, consulte Pré-visualizar as alterações à implementação do Azure ao utilizar as instruções de utilização do Microsoft Learn.

Instalar Azure PowerShell módulo

Para utilizar as secções no PowerShell, tem de ter a versão 4.2 ou posterior do módulo Az.

Para instalar o módulo, utilize:

Install-Module -Name Az -Force

Para obter mais informações sobre como instalar módulos, consulte Instalar Azure PowerShell.

Instalar o módulo CLI do Azure

Para utilizar as secções no Azure CLI, tem de ter o Azure CLI 2.14.0 ou posterior. Se necessário, instale a versão mais recente do Azure CLI.

Ver resultados

Quando utiliza o PowerShell ou o Azure CLI, a saída inclui resultados com códigos de cores que o ajudam a ver os diferentes tipos de alterações.

Bicep deployment what-if operation fullresourcepayload and change types

O resultado do texto é:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner: "Team A"
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Nota

A operação de e-se não consegue resolver a função de referência. Sempre que definir uma propriedade para uma expressão de modelo que inclua a função de referência, os relatórios de e-se da propriedade serão alterados. Este comportamento ocorre porque compara o valor atual da propriedade (como ou por um valor booleano) com a expressão de modelo truefalse não resolvida. É claro que estes valores não correspondem. Quando implementar o ficheiro Bicep, a propriedade só será alterada quando a expressão do modelo se resolver num valor diferente.

Comandos de E-se

Azure PowerShell

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize New-AzResourceGroupDeployment ou New-AzSubscriptionDeployment. Adicione -Whatif o parâmetro do parâmetro ao comando implementação.

  • New-AzResourceGroupDeployment -Whatif para implementação de grupos de recursos
  • New-AzSubscriptionDeployment -Whatif e New-AzDeployment -Whatif para implementar ao nível da subscrição

Pode utilizar o parâmetro switch para pré-visualizar as alterações e -Confirm ser-lhe-á pedido para continuar com a implementação.

  • New-AzResourceGroupDeployment -Confirm para implementação de grupos de recursos
  • New-AzSubscriptionDeployment -Confirm e New-AzDeployment -Confirm para implementar ao nível da subscrição

Os comandos anteriores devolvem um resumo de texto que pode inspecionar manualmente. Para obter um objeto que possa inspecionar por programação as alterações, utilize Get-AzResourceGroupDeploymentWhatIfResult ou Get-AzSubscriptionDeploymentWhatIfResult.

  • $results = Get-AzResourceGroupDeploymentWhatIfResult para implementação de grupos de recursos
  • $results = Get-AzSubscriptionDeploymentWhatIfResult ou $results = Get-AzDeploymentWhatIfResult para implementar ao nível da subscrição

Azure CLI

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize:

Pode utilizar o botão (ou o seu breve formulário ) para pré-visualizar as alterações e ser-lhe-á pedido para continuar --confirm-with-what-if-c com a implementação. Adicione este botão para:

Por exemplo, utilize az deployment group create --confirm-with-what-if ou -c para implementções de grupos de recursos.

Os comandos anteriores devolvem um resumo de texto que pode inspecionar manualmente. Para obter um objeto JSON onde pode inspecionar alterações por programação, utilize a --no-pretty-print seta para alternar. Por exemplo, utilize az deployment group what-if --no-pretty-print para implementação de grupos de recursos.

Se quiser devolver os resultados sem cores, abra o ficheiro de configuração CLI do Azure. Defina no_color para sim.

Azure REST API

Para a REST API, utilize:

Alterar tipos

A operação de "e-se" lista seis tipos diferentes de alterações:

  • Criar:o recurso não existe atualmente mas está definido no ficheiro Bicep. O recurso será criado.
  • Eliminar :este tipo de alteração só se aplica quando utiliza o modo completo para a implementação de modelos JSON. O recurso existe, mas não está definido no ficheiro Bicep. Com o modo completo, o recurso será eliminado. Apenas os recursos que suportem a eliminação do modo completo estão incluídos neste tipo de alteração.
  • Ignorar:o recurso existe, mas não é definido no ficheiro Bicep. O recurso não será implementado ou modificado.
  • NoChange:o recurso existe e é definido no ficheiro Bicep. O recurso será implementado de novo, mas as propriedades do recurso não serão alteradas. Este tipo de alteração é devolvido quando o ResultFormat está definido como , que é o valor predefinido.
  • Modificar:o recurso existe e é definido no ficheiro Bicep. O recurso será implementado de novo e as propriedades do recurso serão alteradas. Este tipo de alteração é devolvido quando o ResultFormat está definido como , que é o valor predefinido.
  • Implementação: orecurso existe e é definido no ficheiro Bicep. O recurso será implementado de novo. As propriedades do recurso podem ou não ser alteradas. A operação devolve este tipo de alteração quando não tiver informações suficientes para determinar se alguma propriedade será alterada. Só verá esta condição quando o ResultFormat estiver definido como .

Formato de resultado

Pode controlar o nível de detalhe que é devolvido sobre as alterações previstas. Tem duas opções:

  • FullResourcePayloads - devolve uma lista de recursos que serão alterados e detalhes sobre as propriedades que serão alterados
  • ResourceIdOnly - devolve uma lista de recursos que será alterada

O valor predefinido é FullResourcePayloads.

Para os comandos de implementação do PowerShell, utilize o -WhatIfResultFormat parâmetro. Nos comandos de objeto programático, utilize o ResultFormat parâmetro.

Para CLI do Azure, utilize o --result-format parâmetro.

Os seguintes resultados mostram os dois formatos de saída diferentes:

  • Payloads de recursos completos

    Resource and property changes are indicated with these symbols:
      - Delete
      + Create
      ~ Modify
    
    The deployment will update the following scope:
    
    Scope: /subscriptions/./resourceGroups/ExampleGroup
    
      ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
        - tags.Owner: "Team A"
        ~ properties.addressSpace.addressPrefixes: [
          - 0: "10.0.0.0/16"
          + 0: "10.0.0.0/15"
          ]
        ~ properties.subnets: [
          - 0:
    
            name:                     "subnet001"
            properties.addressPrefix: "10.0.0.0/24"
    
          ]
    
    Resource changes: 1 to modify.
    
  • Apenas ID do Recurso

    Resource and property changes are indicated with this symbol:
      ! Deploy
    
    The deployment will update the following scope:
    
    Scope: /subscriptions/./resourceGroups/ExampleGroup
    
      ! Microsoft.Network/virtualNetworks/vnet-001
    
    Resource changes: 1 to deploy.
    

Executar a operação de e-se

Configurar ambiente

Para ver como funcionam as secções, vamos executar alguns testes. Em primeiro lugar, implemente um ficheiro Bicep que crie uma rede virtual. Irá utilizar esta rede virtual para testar a forma como as alterações são comunicadas por e-se. Transfira uma cópia do ficheiro Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2021-02-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
    Owner: 'Team A'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet001'
        properties: {
          addressPrefix: '10.0.0.0/24'
        }
      }
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Para implementar o ficheiro Bicep, utilize:

New-AzResourceGroup `
  -Name ExampleGroup `
  -Location centralus
New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-before.bicep"

Modificação de teste

Quando a implementação estiver concluída, estará pronto para testar a operação de e-se. Desta vez, implementa um ficheiro Bicep que altera a rede virtual. Falta uma etiqueta original, uma sub-rede foi removida e o prefixo do endereço foi alterado. Transfira uma cópia do ficheiro Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2021-02-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/15'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Para ver as alterações, utilize:

New-AzResourceGroupDeployment `
  -Whatif `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-after.bicep"

O resultado de e-se parece semelhante a:

Bicep deployment what-if operation output

O resultado do texto é:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner:                    "Team A"
    + properties.enableVmProtection: false
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Repare na parte superior do resultado que as cores são definidas para indicar o tipo de alterações.

Na parte inferior do resultado, mostra que o proprietário da etiqueta foi eliminado. O prefixo do endereço mudou de 10.0.0.0/16 para 10.0.0.0/15. A sub-rede denominada sub-rede001 foi eliminada. Lembre-se de que estas alterações não foram implementadas. Verá uma pré-visualização das alterações que ocorrerão se implementar o ficheiro Bicep.

Algumas das propriedades listadas como eliminadas não mudam. As propriedades podem ser comunicadas incorretamente como eliminadas quando não estão no ficheiro Bicep, mas são definidas automaticamente durante a implementação como valores predefinidos. Este resultado é considerado "ruído" na resposta de que se trata. O recurso implementado final terá os valores definidos para as propriedades. À medida que a operação de "e-se" amadurece, estas propriedades serão filtradas para fora do resultado.

Avaliar programaticamente os resultados de e-se

Agora, vamos avaliar por programação os resultados de que se deve ao definir o comando para uma variável.

$results = Get-AzResourceGroupDeploymentWhatIfResult `
  -ResourceGroupName ExampleGroup `
  --template-file "what-if-after.bicep"

Pode ver um resumo de cada alteração.

foreach ($change in $results.Changes)
{
  $change.Delta
}

Confirmar eliminação

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize o parâmetro confirmar parâmetro com o comando Implementação. Se as alterações estiverem conforme esperado, responda que pretende que a implementação seja concluída.

New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -Confirm `
  -TemplateFile "what-if-after.bicep"

Bicep deployment what-if operation output deployment mode complete

O resultado do texto é:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner:                    "Team A"
    + properties.enableVmProtection: false
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Are you sure you want to execute the deployment?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

Verá as alterações esperadas e pode confirmar que pretende que a implementação seja executada.

Limpar recursos

Quando já não precisar dos recursos de exemplo, utilize o Azure CLI ou Azure PowerShell para eliminar o grupo de recursos.

az group delete --name ExampleGroup

SDKs

Pode utilizar a operação de que precisa através dos SDKs do Azure.

Passos seguintes

  • Para utilizar a operação de e-ARM num pipeline, consulte Testar ARM com What-If num pipeline.
  • Se notar resultados incorretos da operação de what-if, reporte os problemas em https://aka.ms/whatifissues .
  • Para um módulo Microsoft Learn que abrange a utilização de se, consulte Pré-visualizar alterações e validar recursos do Azure utilizando o toolkitde teste de ARM modelo .