在 Azure 自动化中管理变量Manage variables in Azure Automation

变量资产是可供自动化帐户中的所有 Runbook 和 DSC 配置使用的值。Variable assets are values that are available to all runbooks and DSC configurations in your Automation account. 你可以在 Azure 门户、PowerShell、Runbook 或 DSC 配置中管理它们。You can manage them from the Azure portal, from PowerShell, within a runbook, or in a DSC configuration.

自动化变量可用于以下方案:Automation variables are useful for the following scenarios:

  • 在多个 Runbook 或 DSC 配置之间共享某个值。Sharing a value among multiple runbooks or DSC configurations.

  • 在同一 Runbook 或 DSC 配置中的多个作业之间共享某个值。Sharing a value among multiple jobs from the same runbook or DSC configuration.

  • 通过门户或 PowerShell 命令行管理 Runbook 或 DSC 配置使用的值。Managing a value used by runbooks or DSC configurations from the portal or from the PowerShell command line. 例如,一组常用配置项,包括特定的 VM 名称列表、特定资源组、AD 域名等。An example is a set of common configuration items, such as a specific list of VM names, a specific resource group, an AD domain name, and more.

Azure 自动化会持久保存变量,因此即使 Runbook 或 DSC 配置失败,变量也仍然可用。Azure Automation persists variables and makes them available even if a runbook or DSC configuration fails. 此行为允许一个 Runbook 或 DSC 配置设置的值随后由另一个 Runbook 使用,或由同一 Runbook 或 DSC 配置在下次运行时使用。This behavior allows one runbook or DSC configuration to set a value that is then used by another runbook, or by the same runbook or DSC configuration the next time it runs.

Azure 自动化会安全存储每个加密的变量。Azure Automation stores each encrypted variable securely. 创建变量时,可以指定将其加密,并由 Azure 自动化将其作为安全资产进行存储。When you create a variable, you can specify its encryption and storage by Azure Automation as a secure asset. 创建变量后,除非重新创建变量,否则将无法更改其加密状态。After you create the variable, you can't change its encryption status without re-creating the variable. Azure 安全中心建议对所有 Azure 自动化变量进行加密,如自动化帐户变量应进行加密中所述。An Azure Security Center recommendation is to encrypt all Azure Automation variables as described in Automation account variables should be encrypted.

备注

Azure 自动化中的安全资产包括凭据、证书、连接和加密的变量。Secure assets in Azure Automation include credentials, certificates, connections, and encrypted variables. 这些资产已使用针对每个自动化帐户生成的唯一密钥进行加密并存储在 Azure 自动化中。These assets are encrypted and stored in Azure Automation using a unique key that is generated for each Automation account. Azure 自动化将密钥存储在系统管理的 Key Vault 中。Azure Automation stores the key in the system-managed Key Vault. 在存储安全资产之前,自动化会从 Key Vault 加载密钥,然后使用该密钥加密资产。Before storing a secure asset, Automation loads the key from Key Vault and then uses it to encrypt the asset.

变量类型Variable types

使用 Azure 门户创建变量时,必须从下拉列表指定一个数据类型,使门户能够显示用于输入变量值的相应控件。When you create a variable with the Azure portal, you must specify a data type from the dropdown list so that the portal can display the appropriate control for entering the variable value. 下面是可在 Azure 自动化中使用的变量类型:The following are variable types available in Azure Automation:

  • StringString
  • IntegerInteger
  • DateTimeDateTime
  • BooleanBoolean
  • NullNull

该变量并不局限于指定的数据类型。The variable isn't restricted to the specified data type. 但如果要指定不同类型的值,则必须使用 Windows PowerShell 设置该变量。You must set the variable using Windows PowerShell if you want to specify a value of a different type. 如果指示 Not defined,则变量的值将设置为 Null。If you indicate Not defined, the value of the variable is set to Null. 必须使用 Set-AzAutomationVariable cmdlet 或内部 Set-AutomationVariable cmdlet 来设置值。You must set the value with the Set-AzAutomationVariable cmdlet or the internal Set-AutomationVariable cmdlet.

不能使用 Azure 门户来创建或更改复杂变量类型的值。You can't use the Azure portal to create or change the value for a complex variable type. 但是,可以使用 Windows PowerShell 提供任何类型的值。However, you can provide a value of any type using Windows PowerShell. 复杂类型会作为 Complex 对象类型的 Newtonsoft.Json.Linq.JProperty(而不是 PSObject 类型 PSCustomObject)进行检索。Complex types are retrieved as a Newtonsoft.Json.Linq.JProperty for a Complex object type instead of a PSObject type PSCustomObject.

可以通过创建一个数组或哈希表并将其保存到变量,来将多个值存储到单一变量。You can store multiple values to a single variable by creating an array or hashtable and saving it to the variable.

备注

VM 名称变量最多可以包含 80 个字符。VM name variables can be a maximum of 80 characters. 资源组变量最多可以包含 90 个字符。Resource group variables can be a maximum of 90 characters. 请参阅 Azure 资源的命名规则和限制See Naming rules and restrictions for Azure resources.

用于访问变量的 PowerShell cmdletPowerShell cmdlets to access variables

下表中的 cmdlet 使用 PowerShell 创建和管理自动化变量。The cmdlets in the following table create and manage Automation variables with PowerShell. 它们作为 Az 模块的一部分提供。They ship as part of the Az modules.

CmdletCmdlet 说明Description
Get-AzAutomationVariableGet-AzAutomationVariable 检索现有变量的值。Retrieves the value of an existing variable. 如果该值为简单类型,则检索相同的类型。If the value is a simple type, that same type is retrieved. 如果为复杂类型,则检索 PSCustomObject 类型。If it's a complex type, a PSCustomObject type is retrieved.
注意: 不能使用此 cmdlet 检索已加密变量的值。Note: You can't use this cmdlet to retrieve the value of an encrypted variable. 只能在 runbook 或 DSC 配置中使用内部 Get-AutomationVariable cmdlet 来执行此操作。The only way to do this is by using the internal Get-AutomationVariable cmdlet in a runbook or DSC configuration. 请参阅用于访问变量的内部 cmdletSee Internal cmdlets to access variables.
New-AzAutomationVariableNew-AzAutomationVariable 创建新变量并设置变量值。Creates a new variable and sets its value.
Remove-AzAutomationVariableRemove-AzAutomationVariable 删除现有变量。Removes an existing variable.
Set-AzAutomationVariableSet-AzAutomationVariable 设置现有变量的值。Sets the value for an existing variable.

用于访问变量的内部 cmdletInternal cmdlets to access variables

下表中的内部 cmdlet 用于访问 Runbook 和 DSC 配置中的变量。The internal cmdlets in the following table are used to access variables in your runbooks and DSC configurations. 这些 cmdlet 附带全局模块 Orchestrator.AssetManagement.CmdletsThese cmdlets come with the global module Orchestrator.AssetManagement.Cmdlets. 有关详细信息,请参阅内部 cmdletFor more information, see Internal cmdlets.

内部 CmdletInternal Cmdlet 说明Description
Get-AutomationVariable 检索现有变量的值。Retrieves the value of an existing variable.
Set-AutomationVariable 设置现有变量的值。Sets the value for an existing variable.

备注

请避免在 Runbook 或 DSC 配置中的 Get-AutomationVariableName 参数中使用变量。Avoid using variables in the Name parameter of Get-AutomationVariable in a runbook or DSC configuration. 使用变量可能会使设计时发现 Runbook 与自动化变量之间的依赖关系变得复杂。Use of the variables can complicate the discovery of dependencies between runbooks and Automation variables at design time.

Get-AutomationVariable 不适用于 PowerShell,只在 runbook 或 DSC 配置中适用。Get-AutomationVariable does not work in PowerShell, but only in a runbook or DSC configuration. 例如,若要查看某个加密变量的值,可以创建一个 runbook 来获取该变量,然后将其写入到输出流:For example, to see the value of an encrypted variable, you might create a runbook to get the variable and then write it to the output stream:

$mytestencryptvar = Get-AutomationVariable -Name TestVariable
Write-output "The encrypted value of the variable is: $mytestencryptvar"

用于访问变量的 Python 2 函数Python 2 functions to access variables

下表中的函数用于在 Python2 runbook 中访问变量。The functions in the following table are used to access variables in a Python 2 runbook.

Python 2 函数Python 2 Functions 说明Description
automationassets.get_automation_variable 检索现有变量的值。Retrieves the value of an existing variable.
automationassets.set_automation_variable 设置现有变量的值。Sets the value for an existing variable.

备注

必须在 Python Runbook 顶部导入 automationassets 模块才能访问资产函数。You must import the automationassets module at the top of your Python runbook to access the asset functions.

创建并获取变量Create and get a variable

备注

如果要删除对变量的加密,则必须删除该变量,并将其重新创建为未加密的变量。If you want to remove the encryption for a variable, you must delete the variable and recreate it as unencrypted.

使用 Azure 门户创建并获取变量Create and get a variable using the Azure portal

  1. 在自动化帐户的左侧窗格中,选择“共享资源”下的“变量” 。From your Automation account, on the left-hand pane select Variables under Shared Resources.
  2. 在“变量”页上,选择“添加变量”。On the Variables page, select Add a variable.
  3. 完成“新建变量”页上的选项,然后选择“创建”保存新变量。 Complete the options on the New Variable page and then select Create to save the new variable.

备注

保存加密的变量后,就不能在门户中查看它。Once you have saved an encrypted variable, it can't be viewed in the portal. 只能更新它。It can only be updated.

在 Windows PowerShell 中创建并获取变量Create and get a variable in Windows PowerShell

Runbook 或 DSC 配置使用 New-AzAutomationVariable cmdlet 创建新的变量并设置其初始值。Your runbook or DSC configuration uses the New-AzAutomationVariable cmdlet to create a new variable and set its initial value. 如果变量已加密,则调用应使用 Encrypted 参数。If the variable is encrypted, the call should use the Encrypted parameter. 脚本可以使用 Get-AzAutomationVariable 检索变量的值。Your script can retrieve the value of the variable using Get-AzAutomationVariable.

备注

PowerShell 脚本无法检索加密的值。A PowerShell script can't retrieve an encrypted value. 只能使用内部 Get-AutomationVariable cmdlet 执行此操作。The only way to do this is to use the internal Get-AutomationVariable cmdlet.

下面的示例演示如何创建字符串变量,然后返回其值。The following example shows how to create a string variable and then return its value.

New-AzAutomationVariable -ResourceGroupName "ResourceGroup01" 
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable' `
-Encrypted $false -Value 'My String'
$string = (Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable').Value

下面的示例演示如何创建复杂类型的变量,并检索其属性。The following example shows how to create a variable with a complex type and then retrieve its properties. 在本例中,我们使用了 Get-AzVM 返回的虚拟机对象(通过指定其属性的子集)。In this case, a virtual machine object from Get-AzVM is used specifying a subset of its properties.

$vm = Get-AzVM -ResourceGroupName "ResourceGroup01" -Name "VM01" | Select Name, Location, Extensions
New-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable" -Encrypted $false -Value $vm

$vmValue = Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable"

$vmName = $vmValue.Name
$vmExtensions = $vmValue.Extensions

文本 Runbook 示例Textual runbook examples

检索和设置变量中的简单值Retrieve and set a simple value from a variable

下面的示例演示如何设置和检索文本 Runbook 中的变量。The following example shows how to set and retrieve a variable in a textual runbook. 此示例假设创建名为 NumberOfIterationsNumberOfRunnings 的整数变量,以及名为 SampleMessage 的字符串变量。This example assumes the creation of integer variables named NumberOfIterations and NumberOfRunnings and a string variable named SampleMessage.

$NumberOfIterations = Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name 'NumberOfIterations'
$NumberOfRunnings = Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name 'NumberOfRunnings'
$SampleMessage = Get-AutomationVariable -Name 'SampleMessage'

Write-Output "Runbook has been run $NumberOfRunnings times."

for ($i = 1; $i -le $NumberOfIterations; $i++) {
    Write-Output "$i`: $SampleMessage"
}
Set-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name NumberOfRunnings -Value ($NumberOfRunnings += 1)

在 Python 2 Runbook 中检索和设置变量Retrieve and set a variable in a Python 2 runbook

以下示例演示如何在 Python2 Runbook 中获取变量、设置变量以及处理关于不存在的变量的异常。The following sample shows how to get a variable, set a variable, and handle an exception for a nonexistent variable in a Python 2 runbook.

import automationassets
from automationassets import AutomationAssetNotFound

# get a variable
value = automationassets.get_automation_variable("test-variable")
print value

# set a variable (value can be int/bool/string)
automationassets.set_automation_variable("test-variable", True)
automationassets.set_automation_variable("test-variable", 4)
automationassets.set_automation_variable("test-variable", "test-string")

# handle a non-existent variable exception
try:
    value = automationassets.get_automation_variable("nonexisting variable")
except AutomationAssetNotFound:
    print "variable not found"

图形 Runbook 示例Graphical runbook examples

在图形 Runbook 中,可以为内部 cmdlet Get-AutomationVariableSet-AutomationVariable 添加活动。In a graphical runbook, you can add activities for the internal cmdlets Get-AutomationVariable or Set-AutomationVariable. 只需在图形编辑器的“库”窗格中右键单击每个变量,然后选择所需的活动即可。Just right-click each variable in the Library pane of the graphical editor and select the activity that you want.

将变量添加到画布

下图显示了在图形 Runbook 中用于更新具有简单值的变量的示例活动。The following image shows example activities to update a variable with a simple value in a graphical runbook. 在此示例中,Get-AzVM 的活动检索单个 Azure 虚拟机,并将计算机名称保存到现有的自动化字符串变量。In this example, the activity for Get-AzVM retrieves a single Azure virtual machine and saves the computer name to an existing Automation string variable. 链接是管道还是序列并不重要,因为代码只需要输出中的单个对象。It doesn't matter whether the link is a pipeline or sequence since the code only expects a single object in the output.

设置简单变量

后续步骤Next steps