ansible.windows.win_shell 模块 – 在目标主机上执行 shell 命令

注意

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

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

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

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

概要 

ansible.windows.win_shell 模块接收命令名称，后跟以空格分隔的参数列表。它类似于 ansible.windows.win_command 模块，但通过目标主机上的 shell（默认为 PowerShell）运行命令。
对于非 Windows 目标，请改用 ansible.builtin.shell 模块。

参数 

参数	注释
chdir 路径	在执行命令之前，将指定的路径设置为当前工作目录
creates 路径	路径或路径过滤器模式；当目标主机上存在引用的路径时，将跳过该任务。
executable 路径	更改用于执行命令的 shell（例如，`cmd`）。目标 shell 必须接受 `/c` 参数，后跟要执行的原始命令行。
free_form 字符串 / 必需	ansible.windows.win_shell 模块接收要运行的自由格式命令。实际上没有名为“free form”的参数。请参阅示例！
no_profile 布尔值	在运行命令之前不加载用户配置文件。仅当使用 PowerShell 作为可执行文件时，此操作才有效。选项 `false` ←（默认） `true`
output_encoding_override 字符串	此选项会覆盖 stdout/stderr 输出的编码。当需要运行忽略控制台代码页的命令时，可以使用此选项。您应该仅在极少数情况下才需要使用此选项。此值可以是基于 `[System.Text.Encoding]::GetEncodings(`) 输出的任何有效编码 `Name`。请参阅 https://docs.microsoft.com/dotnet/api/system.text.encoding.getencodings。
removes 路径	路径或路径过滤器模式；当目标主机上不存在引用的路径时，将跳过该任务。
stdin 字符串	将命令的 stdin 直接设置为指定的值。

备注 

注意

如果要安全且可预测地运行可执行文件，则最好使用 ansible.windows.win_command 模块。编写 playbook 时的最佳实践将遵循使用 ansible.windows.win_command 的趋势，除非明确需要 win_shell。在运行临时命令时，请使用您的最佳判断。
WinRM 将不会从命令执行中返回，直到创建的所有子进程都已退出。因此，无法使用 ansible.windows.win_shell 来生成长时间运行的子进程或后台进程。请考虑创建 Windows 服务来管理后台进程。 - 如果您要将 PowerShell 脚本的输出捕获为结构化对象，请考虑使用 ansible.windows.win_powershell。

另请参阅 

另请参阅

community.windows.psexec: 基于 PsExec 模型在远程 Windows 主机上运行命令。
ansible.builtin.raw: 执行一个低级且不完善的命令。
ansible.builtin.script: 在传输本地脚本后，在远程节点上运行该脚本。
ansible.builtin.shell: 在目标上执行 shell 命令。
ansible.windows.win_command: 在远程 Windows 节点上执行命令。
ansible.windows.win_powershell: 运行 PowerShell 脚本。
community.windows.win_psexec: 以其他（特权）用户的身份（远程）运行命令。

示例 

- name: Execute a command in the remote shell, stdout goes to the specified file on the remote
  ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt

- name: Change the working directory to somedir/ before executing the command
  ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt
  args:
    chdir: C:\somedir

- name: Run a command with an idempotent check on what it creates, will only run when somedir/somelog.txt does not exist
  ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt
  args:
    chdir: C:\somedir
    creates: C:\somelog.txt

- name: Run a command under a non-Powershell interpreter (cmd in this case)
  ansible.windows.win_shell: echo %HOMEDIR%
  args:
    executable: cmd
  register: homedir_out

- name: Run multi-lined shell commands
  ansible.windows.win_shell: |
    $value = Test-Path -Path C:\temp
    if ($value) {
        Remove-Item -Path C:\temp -Force
    }
    New-Item -Path C:\temp -ItemType Directory

- name: Retrieve the input based on stdin
  ansible.windows.win_shell: '$string = [Console]::In.ReadToEnd(); Write-Output $string.Trim()'
  args:
    stdin: Input message

- name: Run a PowerShell script with -NoProfile
  ansible.windows.win_shell: C:\somescript.ps1
  args:
    no_profile: true

返回值 

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

键	描述
cmd 字符串	任务执行的命令。已返回：始终示例： `"rabbitmqctl join_cluster rabbit@main"`
delta 字符串	命令执行的增量时间。已返回：始终示例： `"0:00:00.325771"`
end 字符串	命令执行的结束时间。已返回：始终示例： `"2016-02-25 09:18:26.755339"`
msg 布尔值	已更改。已返回：始终示例： `true`
rc 整数	命令返回代码（0 表示成功）。已返回：始终示例： `0`
start 字符串	命令执行的开始时间。已返回：始终示例： `"2016-02-25 09:18:26.429568"`
stderr 字符串	命令标准错误。已返回：始终示例： `"ls: cannot access foo: No such file or directory"`
stdout 字符串	命令的标准输出。已返回：始终示例: `"正在集群节点 rabbit@slave1 与 rabbit@main ..."`
stdout_lines 列表 / 元素=字符串	命令的标准输出按行分割。已返回：始终示例: `["u'正在集群节点 rabbit@slave1 与 rabbit@main ...'"]`

作者

Matt Davis (@nitzmahone)