ansible.windows.win_powershell 模块 – 运行 PowerShell 脚本

注意

此模块是 ansible.windows 集合 (版本 2.5.0) 的一部分。

如果您使用的是 ansible 软件包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install ansible.windows。

要在 playbook 中使用它，请指定：ansible.windows.win_powershell。

ansible.windows 1.5.0 中的新增功能

概要

• 运行 PowerShell 脚本并以结构化格式输出数据。

• 使用 ansible.windows.win_command 或 ansible.windows.win_shell 来运行具有 stdout、stderr 和 rc 结果的传统 PowerShell 进程。

参数

参数	注释
arguments 列表 / 元素=字符串	在另一个 PowerShell 进程中运行脚本时，传递给 *executable* 的参数列表。 这些不是传递给 *script* 的参数，为此目的使用 *parameters*。
chdir 字符串	启动脚本时要设置的 PowerShell 位置。 这可以是任何 PowerShell 提供程序中的位置。 默认位置取决于许多因素，如果使用相对路径，则设置此选项。
creates 字符串	路径或路径过滤器模式；当目标主机上存在引用的路径时，任务将被跳过。
depth 整数	为 result、output 和 information[x].message_data 序列化返回值的深度。 这还控制由 $Ansible.Diff 设置的 diff 输出的深度。 将其设置为更高的值会大大增加需要返回的数据量。 默认值： 2
error_action 字符串	在执行 *script* 之前要设置的 $ErrorActionPreference。 silently_continue 将忽略任何错误和引发的异常。 continue 是 PowerShell 中的默认行为，错误存在于 *error* 返回值中，但只有终止异常才会阻止脚本继续并将其设置为失败。 stop 将错误视为异常，将停止脚本并将其设置为失败。 选项 "silently_continue" "continue" ← (默认值) "stop"
executable 字符串	要运行脚本的自定义 PowerShell 可执行文件。 未定义时，脚本将在当前模块 PowerShell 解释器中运行。 远程 PowerShell 和 *executable* 指定的 PowerShell 都必须在 PowerShell v5.1 或更高版本上运行。 设置此值可能会更改 output 返回值中返回的值，具体取决于底层 .NET 类型。
parameters 字典	作为键值对传递到脚本的参数。 键对应于参数名称，值是该参数的值。
removes 字符串	路径或路径过滤器模式；当目标主机上**不存在**引用的路径时，任务将被跳过。
script 字符串 / 必需	要运行的 PowerShell 脚本。
sensitive_parameters 列表 / 元素=字典	作为 SecureString 或 PSCredential 传递到脚本的参数。 每个敏感值都将标记为 no_log 以确保它们不会在模块调用参数日志中公开。 *value* 子选项可用于创建 SecureString 值，而 *username* 和 *password* 可用于创建 PSCredential 值。
name 字符串 / 必需	要将此值传递到的参数的名称。
password 字符串	PSCredential 值的 Password。 这与 *value* 互斥，并且在提供 *username* 时必须设置。
username 字符串	PSCredential 值的 UserName。 这与 *value* 互斥。 此值**不会**添加到 no_log 列表中。
value 字符串	要作为 *name* 指定的参数的 SecureString 传递的字符串。 这与 *username* 和 *password* 互斥。

备注

注意

• 当抛出终止异常或 error_action=stop 并引发普通错误记录时，模块将设置为失败。

• 输出值使用自定义过滤器进行处理，虽然它与 ConvertTo-Json 结果大多匹配，但以下值类型有所不同。

• DateTime 将是 UTC 中的 ISO 8601 字符串，DateTimeOffset 将具有值指定的偏移量。

• Enum 将包含一个字典，其中 Type、String、Value 分别为类型名称、字符串表示和原始整数值。

• Type 将包含一个字典，其中 Name、FullName、AssemblyQualifiedName、BaseType 分别为类型名称、包括命名空间的类型名称、定义类型的完整程序集名称以及它从中派生的基类型。

• 脚本可以访问$Ansible变量，在其中可以设置Result、Changed、Failed、Diff，或访问Tmpdir。

• $Ansible.Result是一个原样返回给控制器的值。

• $Ansible.Diff添加于ansible.windows的1.12.0版本中，是一个字典，设置为差异结果，Ansible可以解读。

• $Ansible.Changed可以设置为true或false，以反映模块是否进行了更改。默认设置为true。

• $Ansible.Failed如果脚本想要将失败返回给控制器，可以设置为true。

• $Ansible.Tmpdir是临时目录的路径，用作模块完成后清理的临时位置。

• $Ansible.Verbosity显示此 playbook 的 Ansible 详细程度级别。允许脚本根据详细程度设置 VerbosePreference/DebugPreference。于 1.9.0 版本中添加。

• 任何主机/控制台直接输出，例如Write-Host或[Console]::WriteLine，不被视为输出对象，它们作为字符串返回在 *host_out* 和 *host_err* 中。

• 任何输出流对象都作为列表返回在 *output* 中。这不仅适用于Write-Output及其内置别名echo，也适用于隐式输出；例如，Write-Output "foo"和"foo"给出相同的结果。

• 除非脚本定义了[CmdletBinding(SupportsShouldProcess]，否则模块将在检查模式下跳过运行脚本。

参见

另请参见

ansible.windows.win_command

在远程 Windows 节点上执行命令。

ansible.windows.win_shell

在目标主机上执行 shell 命令。

示例

- name: Run basic PowerShell script
  ansible.windows.win_powershell:
    script: |
      echo "Hello World"

- name: Run PowerShell script with parameters
  ansible.windows.win_powershell:
    script: |
      [CmdletBinding()]
      param (
          [String]
          $Path,

          [Switch]
          $Force
      )

      New-Item -Path $Path -ItemType Directory -Force:$Force
    parameters:
      Path: C:\temp
      Force: true

- name: Run PowerShell script that modifies the module changed result
  ansible.windows.win_powershell:
    script: |
      if (Get-Service -Name test -ErrorAction SilentlyContinue) {
          Remove-Service -Name test
      }
      else {
          $Ansible.Changed = $false
      }

- name: Run PowerShell script in PowerShell 7
  ansible.windows.win_powershell:
    script: |
      $PSVersionTable.PSVersion.Major
    executable: pwsh.exe
    arguments:
      - -ExecutionPolicy
      - ByPass
  register: pwsh_output
  failed_when:
    - pwsh_output.output[0] != 7

- name: Run code in check mode
  ansible.windows.win_powershell:
    script: |
      [CmdletBinding(SupportsShouldProcess)]
      param ()

      # Use $Ansible to detect check mode
      if ($Ansible.CheckMode) {
          echo 'running in check mode'
      }
      else {
          echo 'running in normal mode'
      }

      # Use builtin ShouldProcess (-WhatIf)
      if ($PSCmdlet.ShouldProcess('target')) {
          echo 'also running in normal mode'
      }
      else {
          echo 'also running in check mode'
      }
  check_mode: true

- name: Return a failure back to Ansible
  ansible.windows.win_powershell:
    script: |
      if (Test-Path C:\bad.file) {
          $Ansible.Failed = $true
      }

- name: Define when the script made a change or not
  ansible.windows.win_powershell:
    script: |
      if ((Get-Item WSMan:\localhost\Service\Auth\Basic).Value -eq 'true') {
          Set-Item WSMan:\localhost\Service\Auth\Basic -Value false
      }
      else {
          $Ansible.Changed = $true
      }

- name: Define when to enable Verbose/Debug output
  ansible.windows.win_powershell:
    script: |
      if ($Ansible.Verbosity -ge 3) {
          $VerbosePreference = "Continue"
      }
      if ($Ansible.Verbosity -eq 5) {
          $DebugPreference = "Continue"
      }
      Write-Output "Hello World!"
      Write-Verbose "Hello World!"
      Write-Debug "Hello World!"

- name: Set sensitive parameter value as SecureString parameter
  ansible.windows.win_powershell:
    script: |
      param(
          [string]$Uri,
          [SecureString]$Token
      )

      Invoke-WebRequest -Uri $Uri -Token $Token
    parameters:
      Uri: foo
    sensitive_parameters:
      - name: Token
        value: '{{ sensitive_value }}'

- name: Set credential parameter
  ansible.windows.win_powershell:
    script: |
      param(
          [string]$Uri,
          [PSCredential]$Credential
      )

      Invoke-WebRequest -Uri $Uri -Credential $Credential
    parameters:
      Uri: foo
    sensitive_parameters:
      - name: Credential
        username: CredUserName
        password: '{{ sensitive_value }}'

返回值

常用返回值已在此处记录，以下是此模块特有的字段

键	描述
debug 列表 / 元素=字符串	脚本创建的一系列警告消息。 仅当$DebugPreference = 'Continue'时，调试消息才会显示。 返回值：始终 示例：["debug record"]
error 列表 / 元素=字典	脚本创建的一系列错误记录。 返回值：始终
category_info 字典	有关错误记录的更多信息。 返回值：成功
activity 字符串	遇到错误的操作说明。 返回值：始终 示例："Write-Error"
category 字符串	错误记录的类别名称。 返回值：始终 示例："NotSpecified"
category_id 整数	类别的整数表示。 返回值：始终 示例：0
reason 字符串	错误说明。 返回值：始终 示例："WriteErrorException"
target_name 字符串	目标对象的说明。 如果没有指定目标，则可以为空字符串。 返回值：始终 示例："C:\\Windows"
target_type 字符串	目标对象类型的说明。 如果没有指定目标对象，则可以为空字符串。 返回值：始终 示例："String"
error_details 字典	有关 ErrorRecord 的其他详细信息。 如果没有其他详细信息，则可以为 null。 返回值：成功
message 字符串	错误记录的消息。 返回值：始终 示例："Specific error message"
recommended_action 字符串	发生此错误时的建议操作。 除非生成错误的代码显式添加此项，否则为空。 返回值：始终 示例："Delete file"
exception 字典	有关错误记录背后异常的详细信息。 返回值：成功
help_link 字符串	指向异常帮助详细信息的链接。 可能未设置，因为它取决于 .NET 异常类是否提供此信息。 返回值：始终 示例："https://docs.ansible.org.cn/"
hresult 整数	分配给此异常的有符号整数。 可能未设置，因为它取决于 .NET 异常类是否提供此信息。 返回值：始终 示例：-1
inner_exception 字典	如果存在内部异常详细信息。 该字典包含与普通异常相同的键。 返回值：始终
message 字符串	异常消息。 返回值：始终 示例："The method ran into an error"
source 字符串	导致错误的应用程序或对象的名称。 这可能是一个空字符串，因为它取决于引发异常的代码。 返回值：始终 示例："C:\\Windows"
type 字符串	异常类的完整 .NET 类型。 返回值：始终 示例："System.Exception"
fully_qualified_error_id 字符串	错误情况的唯一标识符 如果创建记录时未指定 ID，则可能为 null。 返回值：始终 示例："ParameterBindingFailed"
output 字符串	通常在 PowerShell 控制台中看到的格式化错误记录消息。 返回值：始终 示例："Write-Error \"error\" : error\n    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException\n    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException\n"
pipeline_iteration_info 列表 / 元素=整数	创建此记录时管道的状态。 这些值是基于 0 的索引。 每个元素条目代表管道语句中的命令索引。 每个元素的值代表该命令中的管道输入索引。 例如，'C:\Windows', 'C:\temp' | Get-ChildItem | Get-Item，[1, 2, 9]分别表示在该管道中第一个、第二个和第三个命令的第二个、第三个和第九个输出中发生错误。 返回值：始终 示例：[0, 0]
script_stack_trace 字符串	错误记录的脚本堆栈跟踪。 返回值：始终 示例："at <ScriptBlock>, <No file>: line 1"
target_object 任意	发生错误的对象。 如果创建记录时未指定对象，则可能为 null。 此对象的类型取决于错误记录本身。 如果该值是复杂类型，它将遵循指定的depth限制。 返回值：始终 示例："C:\\Windows"
host_err 字符串	写入主机错误输出（通常是 stderr）的字符串。 这与发送到 PowerShell 中错误流的对象不同。 返回值：始终 示例："Error 1\nError 2"
host_out 字符串	写入主机输出（通常是 stdout）的字符串。 这与发送到 PowerShell 中输出流的对象不同。 返回值：始终 示例："Line 1\nLine 2"
information 列表 / 元素=字典	脚本创建的一系列信息记录。 信息流仅在 PowerShell v5 中添加，较旧的版本的值始终为空列表。 返回值：始终
message_data 复杂	与记录关联的消息数据。 此处的价值可以是任何类型。 返回值：始终 示例："information record"
source 字符串	记录的来源。 返回值：始终 示例："Write-Information"
tags 列表 / 元素=字符串	与记录关联的一系列标签。 返回值：始终 示例：["Host"]
time_generated 字符串	生成记录的时间。 这是以 ISO 8601 格式的字符串表示的 UTC 时间。 返回值：始终 示例： "2021-02-11T04:46:00.4694240Z"
output 列表 / 元素=字符串	包含脚本输出的所有对象的列表。 列表元素可以是任何内容，因为它取决于运行的内容。 返回值：始终 示例： ["output 1", 2, ["inner list"], {"key": "value"}, "None"]
result 复杂	由脚本中的$Ansible.Result设置的值。 默认为空字典，但脚本可以将其设置为任何值。 返回值：始终 示例： {"key": "value", "other key": 1}
verbose 列表 / 元素=字符串	脚本创建的一系列警告消息。 只有当$VerbosePreference = 'Continue'时，才会显示详细消息。 返回值：始终 示例： ["verbose record"]
warning 列表 / 元素=字符串	脚本创建的一系列警告消息。 只有当$WarningPreference = 'Continue'时，才会显示警告消息。 返回值：始终 示例： ["warning record"]

作者

• Jordan Borean (@jborean93)

资源链接

• 问题追踪器
• 代码仓库
• 通信