Bicep 部署假設狀況作業

文章
09/26/2024

部署 Bicep 檔案之前，您可以預覽將會發生的變更。 Azure Resource Manager 提供假設狀況作業，可讓您了解部署 Bicep 檔案時的資源變更情況。 what-if 作業不會對現有的資源進行任何變更。而是預測指定 Bicep 檔案部署時的變更。

您可以搭配 Azure PowerShell、Azure CLI 或 REST API 作業來使用假設狀況作業。資源群組、訂閱、管理群組和租用戶層級部署都支援假設狀況。

在假設狀況作業期間，不支援評估和擴充 templateLink。因此，在巢狀部署中使用範本連結所部署的任何資源，包括範本規格參考在內，都不會顯示在假設狀況作業結果中。

訓練資源

如果您比較想要透過逐步指導來了解假設狀況作業，請參閱使用假設狀況預覽 Azure 部署變更。

所需的權限

若要部署 Bicep 檔案或 ARM 範本，您需要對即將進行部署的資源具備寫入存取權，並可存取 Microsoft.Resources/部署資源類型上的所有作業。例如，若要部署虛擬機器，您需要 Microsoft.Compute/virtualMachines/write 和 Microsoft.Resources/deployments/* 權限。假設狀況作業具有相同的權限需求。

如需角色與權限的清單，請參閱 Azure 內建角色。

假設狀況限制

假設狀況會展開巢狀範本，直到達到這些限制為止：

500 個巢狀範本。
位於跨資源群組部署中的 800 個資源群組。
展開巢狀範本花費 5 分鐘。

達到其中一個限制時，剩餘資源的變更類型會設定為忽略。

安裝 Azure PowerShell 模組

若要在 PowerShell 中使用假設狀況，您必須具有 4.2 版或更新版本的 Az 模組。

若要安裝此模組，請使用：

Install-Module -Name Az -Force

如需安裝模組的詳細資訊，請參閱安裝 Azure PowerShell。

安裝 Azure CLI 模組

若要在 Azure CLI 中使用假設狀況，您必須具有 Azure CLI 2.14.0 或更新版本。如有需要，請安裝 Azure CLI 的最新版本。

查看結果

當您在 PowerShell 或 Azure CLI 中使用假設狀況時，輸出會包含以色彩編碼的結果，協助您查看不同類型的變更。

Bicep 部署假設狀況作業 fullresourcepayload 和變更類型

文字輸出為：

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.

注意

假設狀況作業無法解析 reference 函式。每次您將屬性設定為包含 reference 函式的範本運算式時，假設狀況都會回報屬性將會變更。因為假設狀況將屬性的目前值 (例如布林值 true 或 false) 與無法解析的範本運算式進行比較，所以會發生此行為。很明顯地，這些值不會相符。當您部署 Bicep 檔案時，只有在範本運算式解析為不同值的情況下，屬性才會變更。

假設狀況命令

Azure PowerShell

若要在部署 Bicep 檔案之前預覽變更，請使用 New-AzResourceGroupDeployment 或 New-AzSubscriptionDeployment。將 -Whatif 切換參數新增至部署命令。

針對資源群組部署使用 New-AzResourceGroupDeployment -Whatif
針對訂閱層級部署使用 New-AzSubscriptionDeployment -Whatif 和 New-AzDeployment -Whatif

您可以使用 -Confirm 切換參數來預覽變更，並收到提示來繼續進行部署。

針對資源群組部署使用 New-AzResourceGroupDeployment -Confirm
針對訂閱層級部署使用 New-AzSubscriptionDeployment -Confirm 和 New-AzDeployment -Confirm

上述命令會傳回可供您手動檢查的文字摘要。若要取得可透過程式設計方式檢查變更的物件，請使用 Get-AzResourceGroupDeploymentWhatIfResult 或 Get-AzSubscriptionDeploymentWhatIfResult。

針對資源群組部署使用 $results = Get-AzResourceGroupDeploymentWhatIfResult
針對訂閱層級部署使用 $results = Get-AzSubscriptionDeploymentWhatIfResult 或 $results = Get-AzDeploymentWhatIfResult

Azure CLI

若要在部署 Bicep 檔案之前預覽變更，請使用：

針對資源群組部署使用 az deployment group what-if
針對訂閱層級部署使用 az deployment sub what-if
針對管理群組部署使用 az deployment mg what-if
針對租用戶部署使用 az deployment tenant what-if

您可以使用 --confirm-with-what-if 切換參數 (或其簡短格式 -c) 來預覽變更，並收到提示來繼續進行部署。將此切換參數新增至：

例如，針對資源群組部署使用 az deployment group create --confirm-with-what-if 或 -c。

上述命令會傳回可供您手動檢查的文字摘要。若要取得可透過程式設計方式檢查變更的 JSON 物件，請使用 --no-pretty-print 切換參數。例如，針對資源群組部署使用 az deployment group what-if --no-pretty-print。

如果您想要傳回不分色彩的結果，請開啟您的 Azure CLI 設定檔。將 no_color 設定為 yes。

Azure REST API

若為 REST API，請使用：

針對資源群組部署使用部署–假設狀況
針對訂閱部署使用部署–訂閱範圍的假設狀況
針對管理群組部署使用部署–管理群組範圍的假設狀況
針對租用戶部署使用部署–租用戶範圍的假設狀況。

變更類型

假設狀況作業會列出七種不同類型的變更：

Create：資源目前不存在，但已在 Bicep 檔案中定義。將會建立資源。
Delete：只有在使用完整模式進行 JSON 範本部署時，才適用此變更類型。資源存在，但未在 Bicep 檔案中定義。將使用「完整模式」刪除資源。只有支援「完整模式」刪除的資源才會包含在此變更類型中。
Ignore：資源存在，但未在 Bicep 檔案中定義。將不會部署或修改資源。在達到擴充巢狀範本的限制時，就會發生此變更類型。請參閱假設狀況限制。
NoChange：資源存在，並且在 Bicep 檔案中定義。資源將會重新部署，但資源的屬性不會變更。當 ResultFormat 設定為 FullResourcePayloads (預設值) 時，就會傳回此變更類型。
NoEffect：此為唯讀屬性，且服務會加以忽略。例如，sku.tier 屬性一律會設定為符合 Microsoft.ServiceBus 命名空間中的 sku.name。
Modify：資源存在，並且在 Bicep 檔案中定義。資源將會重新部署，且資源的屬性將會變更。當 ResultFormat 設定為 FullResourcePayloads (預設值) 時，就會傳回此變更類型。
Deploy：資源存在，並且在 Bicep 檔案中定義。將會重新部署資源。資源的屬性不一定會變更。當作業沒有足夠資訊可判斷是否有任何屬性變更時，作業會傳回此變更類型。您只會在 ResultFormat 設定為 ResourceIdOnly 時看到此情況。

結果格式

您可以控制針對預測變更所傳回的詳細資料層級。您有兩個選擇：

FullResourcePayloads–傳回將變更的資源清單，以及將變更的屬性詳細資料
ResourceIdOnly–傳回將變更的資源清單

預設值為 FullResourcePayloads。

針對 PowerShell 部署命令，請使用 -WhatIfResultFormat 參數。在程式設計物件命令中，使用 ResultFormat 參數。

針對 Azure CLI，請使用 --result-format 參數。

下列結果會顯示兩個不同的輸出格式：

完整資源承載

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.

僅限資源識別碼

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.

執行假設狀況作業

設定環境

為了查看假設狀況的運作方式，讓我們來執行一些測試。首先，部署可建立虛擬網路的 Bicep 檔案。您將使用此虛擬網路來測試假設狀況回報變更的方式。下載 Bicep 檔案的複本。

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-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'
        }
      }
    ]
  }
}

若要部署 Bicep 檔案，請使用：

PowerShell
Azure CLI

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

az group create \
  --name ExampleGroup \
  --location "Central US"
az deployment group create \
  --resource-group ExampleGroup \
  --template-file "what-if-before.bicep"

測試修改

部署完成之後，您就可以開始測試假設狀況作業。這次您會部署變更虛擬網路的 Bicep 檔案。該範本遺漏了其中一個原始標記、移除了一個子網路，而且位址首碼已變更。下載 Bicep 檔案的複本。

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-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'
        }
      }
    ]
  }
}

若要檢視變更，請使用：

PowerShell
Azure CLI

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

az deployment group what-if \
  --resource-group ExampleGroup \
  --template-file "what-if-after.bicep"

what-if 輸出看起來如下：

Bicep 部署假設狀況作業輸出

文字輸出為：

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.

請注意，在輸出的頂端會定義色彩來指出變更的類型。

在輸出的底部，則會顯示已刪除標記擁有者。位址首碼已從 10.0.0.0/16 變更為 10.0.0.0/15。已刪除名為 subnet001 的子網路。請記住，這些變更尚未部署。您可以預覽部署 Bicep 檔案時將會發生的變更。

某些列為已刪除的屬性，實際上不會變更。當屬性不在 Bicep 檔案中時，可能會錯誤地報告為已刪除，但會在部署期間自動設定為預設值。此結果在假設狀況回應中會被視為「雜訊」。最終部署的資源將會設定屬性的值。隨著假設狀況作業成熟，將會從結果中篩選移除這些屬性。

以程式設計方式評估假設狀況結果

現在，讓我們將命令設定為變數，以程式設計方式評估假設狀況結果。

PowerShell
Azure CLI

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

您可以看到每個變更的摘要。

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

results=$(az deployment group what-if --resource-group ExampleGroup --template-file "what-if-after.bicep" --no-pretty-print)

確認刪除

若要在部署 Bicep 檔案之前預覽變更，請使用確認切換參數與部署命令。如果變更如您所預期，請回應您想要完成部署。

PowerShell
Azure CLI

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

az deployment group create \
  --resource-group ExampleGroup \
  --confirm-with-what-if \
  --template-file "what-if-after.bicep"

Bicep 部署假設狀況作業輸出部署模式完成

文字輸出為：

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"):

您會看到預期的變更，並可確認您想要執行部署。

清除資源

當您不再需要範例資源時，請使用 Azure CLI 或 Azure PowerShell 來刪除資源群組。

CLI
PowerShell

az group delete --name ExampleGroup

Remove-AzResourceGroup -Name ExampleGroup

SDK

您可以透過 Azure SDK 使用假設狀況作業。

針對 Python，請使用假設狀況。
針對 JAVA，請使用 DeploymentWhatIf 類別。
針對 .NET，請使用 DeploymentWhatIf 類別。

下一步

若要在管線中使用假設狀況作業，請參閱在管線中使用假設狀況測試 ARM 範本。
如果您發現假設狀況作業的結果不正確，請在 https://aka.ms/whatifissues 回報問題。
如需展示使用假設狀況的 Learn 課程模組，請參閱使用假設狀況與 ARM 範本測試工具組預覽變更及驗證 Azure 資源。

分享方式：

Bicep 部署假設狀況作業

訓練資源

所需的權限

假設狀況限制

安裝 Azure PowerShell 模組

安裝 Azure CLI 模組

查看結果

假設狀況命令

Azure PowerShell

Azure CLI

Azure REST API

變更類型

結果格式

執行假設狀況作業

設定環境

測試修改

以程式設計方式評估假設狀況結果

確認刪除

清除資源

SDK

下一步

意見反映

更多資源