停止浪费时间：更轻松地解析 ARM 输出变量

在 Azure DevOps (AzDo) 中构建 Azure Pipeline 时，将基础设施构建为管道的一部分是很常见的。如果您在 Azure 中构建基础架构，Microsoft 提供了一种称为 Azure 资源管理 (ARM) 模板的基础架构即代码方法。从 Azure 管道中的 ARM 模板调用部署有时会很麻烦，尤其是在处理 ARM 输出变量时。

在本文中，您将了解在 AzDo 管道中使用 ARM 模板最麻烦的方面之一（个人观点）——管理 ARM 输出变量。

了解 ARM 输出和模板

当您通过模板调用 ARM 部署时，ARM 使您能够将输出发送回调用部署的进程，称为“输出”。例如，输出允许您将值从部署中发送回，就像 PowerShell 函数一样。

ARM 输出并不是在 Azure Pipelines 中运行部署所独有的。无论您如何调用 ARM 部署，您始终可以输出值。

如果您需要捕获通过 ARM 模板部署生成的值，可以使用 ARM 模板的 outputs 部分来执行此操作。例如，假设您有一个用于创建 Azure SQL Server 和数据库的 ARM 模板。您将在更大的自动化工作流程（例如 Azure 管道）中调用此 ARM 模板。作为该管道的一部分，您需要知道创建的 SQL Server 的完全限定域名 (FQDN) 和数据库名称。

如果在模板底部包含 outputs 部分，您可以了解如何返回 SQL Server 的 FQDN 和数据库名称，如以下代码片段所示。

以下代码片段假定 ARM 模板中已定义 sqlServerName 和 sqlDbName 参数。

"outputs": {
      "sqlServerName": {
          "value": "[reference(resourceId('Microsoft.Sql/servers', parameters('sqlServerName'))).fullyQualifiedDomainName]",
          "type": "string"
      },
      "databaseName": {
          "value": "[parameters('sqlDbName')]",
          "type": "string"
      }
  }

您可以在下面看到下面的 outputs 部分来自的整个 ARM 模板。 outputs 部分一直到底部。

{
    "$schema": "<https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#>",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "sqlServerName": {
            "type": "string",
            "metadata": {
                "description": "Enter a globally unique hostname for your SQL server"
            }
        },
        "sqlDbName": {
            "type": "string"
        },
        "adminUserName": {
            "type": "string",
            "metadata": {
                "description": "Enter a username for SQL admin"
            }
        },
        "adminPassword": {
            "type": "securestring",
            "metadata": {
                "description": "Enter a password for SQL admin"
            }
        }
    },
    "resources": [
        {
            "name": "[parameters('sqlServerName')]",
            "type": "Microsoft.Sql/servers",
            "apiVersion": "2015-05-01-preview",
            "location": "[resourceGroup().location]",
            "tags": {
                "displayName": "[parameters('sqlServerName')]"
            },
            "properties": {
                "administratorLogin": "[parameters('adminUserName')]",
                "administratorLoginPassword": "[parameters('adminPassword')]"
            },
            "resources": [
                {
                    "type": "firewallRules",
                    "apiVersion": "2015-05-01-preview",
                    "dependsOn": [
                        "[resourceId('Microsoft.Sql/servers', parameters('sqlServerName'))]"
                    ],
                    "location": "[resourceGroup().location]",
                    "name": "AllowAllWindowsAzureIps",
                    "properties": {
                        "startIpAddress": "0.0.0.0",
                        "endIpAddress": "0.0.0.0"
                    }
                }
            ]
        },
        {
            "name": "[concat(parameters('sqlServerName'), '/',parameters('sqlDbName'))]",
            "type": "Microsoft.Sql/servers/databases",
            "apiVersion": "2014-04-01",
            "location": "[resourceGroup().location]",
            "dependsOn": [
                "[resourceId('Microsoft.Sql/servers', parameters('sqlServerName'))]"
            ],
            "properties": {
                "collation": "SQL_Latin1_General_CP1_CI_AS",
                "edition": "Basic",
                "maxSizeBytes": "1073741824",
                "requestedServiceObjectiveName": "Basic"
            }
        }
    ],
    "outputs": {
        "sqlServerName": {
            "value": "[reference(resourceId('Microsoft.Sql/servers', parameters('sqlServerName'))).fullyQualifiedDomainName]",
            "type": "string"
        },
        "databaseName": {
            "value": "[parameters('sqlDbName')]",
            "type": "string"
        }
    }
}

然而，您使用上面的模板调用 ARM 部署，ARM 将返回 SQL Server 的 FQDN 和数据库名称。

在 Azure Pipelines 中调用 ARM 模板

如果要构建基于 YAML 的 Azure 管道，调用 ARM 模板部署的一种流行方法是使用 Azure 资源组部署任务。使用此任务，您可以定义 ARM 模板、要部署到的资源组、模板的路径等。

在以下代码片段中，您可以看到 Azure 管道中定义的 Azure 资源组部署任务的示例。

- task: AzureResourceManagerTemplateDeployment@3
  name: "Compute"
  inputs:
    azureResourceManagerConnection: "ARM"
    subscriptionId: "xxxxxx"
    action: "Create Or Update Resource Group"
    resourceGroupName: xxxxxxxx
    location: "xxxxxx"
    templateLocation: "Linked artifact"
    csmFile: "$(System.DefaultWorkingDirectory)/template.json"
    deploymentMode: "Incremental"
    deploymentOutputs: database_arm

捕获 Azure Pipeline 的 ARM 输出

请注意上面代码片段中的一个属性，特别是 - deploymentOutputs。默认情况下，即使 ARM 模板定义了输出，Azure 管道也不会知道它们。管道将简单地丢弃输出。除非您使用 deploymentOutputs 属性。

deploymentOutputs 属性告诉管道分配通过 ARM 模板中的 outputs 部分返回的所有值，并将它们分配给 JSON 格式的管道变量。在上面的示例中，该管道变量称为database_arm。

database_arm 值不是必需的。您可以随意使用您想要的任何变量名称。

如果下面显示的任务用于部署前面提到的数据库 ARM 模板，则 database_arm 管道变量将包含一个类似于下面代码片段的 JSON 字符串。

{
    "sqlServerName": {
        "value" : "[some sql server name].database.windows.net",
        "type": "string"
    },
    "databaseName": {
        "value" : "[some sql db name]",
        "type": "string"
    }
}

此时，Azure Pipeline 现在会知道名为 database_arm 的输出变量。

解析管道中的 ARM 输出变量

创建包含 ARM 输出的管道变量固然很棒，但您打算用它们做什么呢？您不会无缘无故地创建一个管道变量！

假设您需要将 SQL Server 的 FQDN 和数据库名称传递给稍后在管道中的 Azure SQL 数据库部署任务。您需要将这两个值提供给任务的 ServerName 和 DatabaseName 属性。

我们仍然只有一个名为 database_arm 的管道变量，它由 JSON 字符串组成。按原样，无法将该 JSON 字符串中的 sqlServerName 和 databaseName 的值解析为您需要的实际值。

您希望有两个单独的管道变量，分别名为 databaseName 和 sqlServerName，每个变量仅包含 [some sql db name] 的预期字符串值和[某些sql服务器名称]分别。您需要解析 JSON 并创建两个新的管道变量。

完成后，您希望拥有一个如下例所示的 Azure SQL 数据库部署任务。请注意，绝对没有 database_arm 变量可言。

- task: SqlAzureDacpacDeployment@1
  inputs:
    azureSubscription: 'ARM'
    AuthenticationType: 'server'
    DatabaseName: "$(databaseName)" ## From database ARM deployment
    ServerName: "$(sqlServerName)" ## From database ARM deployment
    SqlUsername: "$(SqlAdminUsername)" ## From keyvault
    SqlPassword: "$(SqlAdminPassword)" ## From keyvault
    deployType: 'SqlTask'
    SqlFile: '$(System.DefaultWorkingDirectory)/file.sql'
    IpDetectionMethod: 'AutoDetect'

那么，如何从充满松散 JSON 文本的 database_arm 管道变量获取名为 databaseName 和 sqlServerName 的两个管道变量呢？电源外壳！

使用 PowerShell 创建管道变量

我们的使命是：从名为 database_arm 的管道变量创建两个名为 databaseName 和 sqlServerName 的管道变量，如下代码片段所示。

{
    "sqlServerName": {
	    "value" : "[some sql server name].database.windows.net",
        "type": "string"
    },
    "databaseName": {
        "value" : "[some sql db name]",
        "type": "string"
    }
}

为了成功完成这一使命，首先，完全忘记 Azure Pipelines。您现在必须创建一些 PowerShell 代码来“转换”这些变量。

定义管道变量

在编写任何代码之前，您首先需要了解如何使用 PowerShell 定义管道变量。这样做需要通过 PowerShell 任务返回两个字符串之一。

要创建输出（和非输出）变量，请返回特定格式的字符串，如下所示。下面的示例将名为 foo 的管道变量设置为值 bar。

"##vso[task.setvariable variable=foo;]bar"

如果您需要管道变量作为输出变量，您可以将 isOutput=true 添加到字符串中，如下所示。

"##vso[task.setvariable variable=foo;isOutput=true]bar"

将这些字符串中的一个或两个包含在某个 PowerShell 中，您将得到：

## Creates a standard pipeline variable called foo and sets the value to bar
Write-Output "##vso[task.setvariable variable=foo;]bar"
## Creates an output variable called foo and sets the value to bar
Write-Output "##vso[task.setvariable variable=foo;isOutput=true]bar"

将 ARM 输出变量转换为特定值

您现在知道可以在 ARM 模板中创建 outputs 部分，在 Azure 管道中部署该模板，并使用管道任务上的 deploymentOutputs 属性来创建管道包含 JSON 字符串的变量，该字符串具有 outputs ARM 模板的值。部分。您还学习了如何使用 PowerShell 创建管道变量。

现在让我们将所有内容整合在一起并尽可能自动化整个过程！

您在上面已经看到，通过 ARM 模板部署创建的 database_arm 管道变量类似于以下代码片段。

{
    "sqlServerName": {
				"value" : "[some sql server name].database.windows.net",
        "type": "string"
    },
    "databaseName": {
				"value" : "[some sql db name]",
        "type": "string"
    }
}

如果该字符串根本不在管道中，您将如何使用 PowerShell 从 JSON 中获取值？

假设您已将上述 JSON 代码段复制并粘贴到本地 PowerShell 会话中名为 $armOutput 的变量中。

$armOutput = @'
{
    "sqlServerName": {
	    "value" : "[some sql server name].database.windows.net",
        "type": "string"
    },
    "databaseName": {
		"value" : "[some sql db name]",
        "type": "string"
    }
}
'@

使用方便的 ConvertFrom-Json cmdlet，您可以轻松地将上述 JSON 字符串转换为 PowerShell 对象。

$armOutputObj = $armOutput | convertfrom-json

一旦 PowerShell 对象中包含 JSON 字符串，您就可以使用每个 PowerShell 对象上的 PSObject.Properties 属性检查所有属性和值，如下所示。

$armOutputObj.PSObject.Properties | ForEach-Object {
    $keyname = $_.Name
    $value = $_.Value.value
    Write-Host "The value of [$keyName] is [$value]"
}

上面的代码片段将产生下面这个美丽的景象。

您现在可以将 $armOutput 中的每个值作为单独的值进行引用。你太接近了！

由于您将在管道中执行上述操作并且需要将这些值设为管道变量，因此请利用您通过 PowerShell 创建管道变量的知识。

$armOutputObj.PSObject.Properties | ForEach-Object {
    $keyname = $_.Name
    $value = $_.Value.value
    ## Creates a standard pipeline variable
    Write-Output "##vso[task.setvariable variable=$keyName;]$value"
		
    ## Creates an output variable
    Write-Output "##vso[task.setvariable variable=$keyName;isOutput=true]$value"
}

现在将上面的代码添加到 PowerShell 管道任务中，如下所示。如果您按照本示例进行操作，现在应该创建了两个管道变量，分别名为 databaseName 和 sqlServerName！

- pwsh: |
	## database_arm is already a pipeline variable returned via the ARM deployment
	## task's deploymentOutputs attribute
	$armOutputObj = $env:database_arm | convertfrom-json
	$armOutputObj.PSObject.Properties | ForEach-Object {
    $keyname = $_.Name
    $value = $_.Value.value

    ## Creates a standard pipeline variable
    Write-Output "##vso[task.setvariable variable=$keyName;]$value"
		
    ## Creates an output variable
    Write-Output "##vso[task.setvariable variable=$keyName;isOutput=true]$value"
	}

更好的是，在 Azure DevOps 项目的源代码库中创建一个 PowerShell 脚本，如下所示。下面的脚本考虑了其他类型的部署输出，例如数组、安全字符串，并且可配置为创建或不创建输出变量。

[CmdletBinding()]
param (
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string]$ArmOutputString,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [switch]$MakeOutput
)

Write-Output "Retrieved input: $ArmOutputString"
$armOutputObj = $ArmOutputString | ConvertFrom-Json

$armOutputObj.PSObject.Properties | ForEach-Object {
    $type = ($_.value.type).ToLower()
    $keyname = $_.Name
    $vsoAttribs = @("task.setvariable variable=$keyName")

    if ($type -eq "array") {
        $value = $_.Value.value.name -join ',' ## All array variables will come out as comma-separated strings
    } elseif ($type -eq "securestring") {
        $vsoAttribs += 'isSecret=true'
    } elseif ($type -ne "string") {
        throw "Type '$type' is not supported for '$keyname'"
    } else {
        $value = $_.Value.value
    }
        
    if ($MakeOutput.IsPresent) {
        $vsoAttribs += 'isOutput=true'
    }

    $attribString = $vsoAttribs -join ';'
    $var = "##vso[$attribString]$value"
    Write-Output -InputObject $var
}

也许您已将上述代码保存到项目源代码库中名为 parse_arm_deployment_output.ps1 的文件中。此时，您只需引用该脚本即可自动创建您选择的 ARM 输出管道变量。

- pwsh: $(System.DefaultWorkingDirectory)/parse_arm_deployment_output.ps1 -ArmOutputString '$(database_arm)' -MakeOutput -ErrorAction Stop

一旦上述 PowerShell 脚本运行，您就可以实现在管道中的未来任务中将这两个变量的值引用为管道变量的目标。

- task: SqlAzureDacpacDeployment@1
  inputs: azureSubscription: 'ARM'
    AuthenticationType: 'server'
    DatabaseName: "$(databaseName)" ## From database ARM deployment
    ServerName: "$(sqlServerName)" ## From database ARM deployment
    SqlUsername: "$(SqlAdminUsername)" ## From keyvault
    SqlPassword: "$(SqlAdminPassword)" ## From keyvault
    deployType: 'SqlTask'
    SqlFile: '$(System.DefaultWorkingDirectory)/file.sql'
    IpDetectionMethod: 'AutoDetect'

结论

在 Azure 管道中管理 ARM 模板、部署和 ARM 输出变量可能具有挑战性。不过，一旦您提出本文中提出的解决方案，您就不必再担心如何实现它的细节。请务必获取本文中引用的 PowerShell 脚本，以便将来为您节省大量时间！