community.windows.win_scheduled_task 模块 – 管理计划任务

注意

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

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

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

要在 playbook 中使用它，请指定：community.windows.win_scheduled_task。

概要

• 创建/修改或删除 Windows 计划任务。

参数

参数	注释
actions 列表 / 元素=字典	要为任务配置的操作列表。 有关如何构建每个列表条目的详细信息，请参见子选项。 创建任务时，必须至少有一个操作，但是删除任务时，这可以是空值或空列表。 此列表的顺序很重要，模块将确保在修改任务时保持顺序。 此模块仅支持 ExecAction 类型，但仍然可以删除旧的旧版类型。
arguments 字符串	要为可执行文件提供的参数字符串。
path 字符串 / 必需	ExecAction 的可执行文件的路径。
working_directory 字符串	运行可执行文件的目标工作目录。
allow_demand_start 布尔值	任务是否可以使用“运行”命令或上下文菜单启动。 选项 否 是
allow_hard_terminate 布尔值	任务是否可以使用 TerminateProcess 终止。 选项 否 是
author 字符串	任务的作者。
compatibility 整数	指示任务与哪个版本的 Task Scheduler 兼容的整数值。 0 表示任务与 AT 命令兼容。 1 表示任务与 Task Scheduler 1.0（Windows Vista、Windows Server 2008 及更早版本）兼容。 2 表示任务与 Task Scheduler 2.0（Windows Vista、Windows Server 2008）兼容。 3 表示任务与 Task Scheduler 2.0（Windows 7、Windows Server 2008 R2）兼容。 4 表示任务与 Task Scheduler 2.0（Windows 10、Windows Server 2016、Windows Server 2019）兼容。 选项 0 1 2 3 4
date 字符串	注册任务的日期。
delete_expired_task_after 字符串	任务过期后，任务计划程序等待多长时间才能删除任务。 任务在与任务关联的所有触发器的 end_boundary 超过之后过期。 这采用 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
description 字符串	任务的描述。
disallow_start_if_on_batteries 布尔值	如果计算机正在使用电池供电，则任务是否不会启动。 选项 否 是
display_name 字符串	在任务计划程序 UI 中显示的用户/组的名称。
enabled 布尔值	任务是否已启用，只有在 yes 时任务才能运行。 选项 否 是
execution_time_limit 字符串	完成任务所需的时间。 设置为 PT0S 时，时间限制无限。 省略时，默认时间限制为 72 小时。 这采用 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
group 字符串	将运行任务的组。 group 和 username 是互斥的，不能同时设置。 logon_type 可以不设置或等于 group。
hidden 布尔值	任务是否会在 UI 中隐藏。 选项 否 是
logon_type 字符串	任务将运行的登录方法。 password 表示密码将被存储，并且任务可以访问网络资源。 s4u 表示将使用现有令牌运行任务，并且不会将密码与任务一起存储。这意味着无法访问网络或加密文件。 interactive_token 表示用户必须已经以交互方式登录，并且将在现有的交互式会话中运行。 group 表示任务将以组身份运行。 service_account 表示系统、本地服务或网络服务等服务帐户将运行任务。 选项 "无" "密码" "s4u" "交互式令牌" "组" "服务帐户" "令牌或密码"
多个实例 整数	一个整数，指示启动已运行的任务时的行为。 0 将与该任务的现有实例并行启动一个新实例。 1 将等待该任务的其他实例运行完毕后再启动自身。 2 如果另一个实例正在运行，则不会启动新实例。 3 将停止任务的其他实例并启动新实例。 选项 0 1 2 3
名称 字符串 / 必需	计划任务的名称（不包括路径）。
密码 字符串	用于运行计划任务的用户帐户的密码。 在未登录用户的情况下运行任务时需要此项，内置服务帐户和组托管服务帐户 (gMSA) 除外。 如果设置此项，除非update_password设置为no并且服务不需要其他更改，否则将始终导致更改。
path 字符串	将存储此任务的任务文件夹。 当state=present且文件夹尚不存在时，将创建该文件夹。 当state=absent且文件夹中没有剩余任务时，将删除该文件夹。 默认值： "\\"
优先级 整数	任务的优先级级别 (0-10)。 创建新任务时，默认值为7。 有关优先级级别的详细信息，请参阅https://msdn.microsoft.com/en-us/library/windows/desktop/aa383512.aspx。
重启次数 整数	任务计划程序将尝试重启任务的次数。
重启间隔 字符串	任务计划程序将尝试重启任务的时间长度。 如果设置此项，则也必须设置restart_count。 最大允许时间为 31 天。 最小允许时间为 1 分钟。 这采用 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
运行级别 别名：runlevel 字符串	用于运行任务的用户权限级别。 如果未指定，则任务将以有限权限创建。 选项 "有限" "最高"
仅在空闲时运行 布尔值	仅当计算机处于空闲状态时，任务是否才运行。 选项 否 是
仅在网络可用时运行 布尔值	只有在网络可用时，任务是否才运行。 选项 否 是
来源 字符串	任务的来源。
启动时可用 布尔值	任务是否可以在其计划时间过去后的任何时间启动。 选项 否 是
状态 字符串	当state=present时，将确保任务存在。 当state=absent时，将确保任务不存在。 选项 "不存在" "存在" ← (默认)
电池供电时停止 布尔值	如果计算机开始使用电池供电，是否停止任务。 选项 否 是
触发器 列表 / 元素=字典	要为任务配置的触发器列表。 有关如何构建每个列表条目的详细信息，请参见子选项。 此列表的顺序很重要，模块将确保在修改任务时保持顺序。 有多种类型的触发器，有关触发器类型及其选项的列表，请参阅https://msdn.microsoft.com/en-us/library/windows/desktop/aa383868.aspx。 下面列出的子选项不是所有触发器类型都需要，请阅读说明以了解更多详细信息。
月份中的日期 字符串	触发器的月份中的日期（1 到 31）。 如果要将触发器设置为任何月份的最后一天，请使用run_on_last_day_of_month。 可以是日期数字列表或逗号分隔的字符串。 当type=monthly时必需。
星期几 字符串	触发器的星期几。 可以是完整星期名称的列表或逗号分隔的字符串，例如 monday 而不是 mon。 当type为weekly时必需。 当type=monthlydow时可选。
延迟 字符串	触发器触发后运行任务的延迟时间。 当type为boot、event、logon、registration、session_state_change时可选。 采用 ISO 8601 持续时间格式P[n]Y[n]M[n]DT[n]H[n]M[n]S。
enabled 布尔值	是否将触发器设置为启用或禁用 用于所有触发器类型。 选项 否 是
结束边界 字符串	触发器停用的结束时间。 采用 ISO 8601 日期时间格式YYYY-MM-DDThh:mm:ss。
execution_time_limit 字符串	任务允许运行的最长时间。 所有触发器类型均可选。 采用 ISO 8601 持续时间格式P[n]Y[n]M[n]DT[n]H[n]M[n]S。
月份 字符串	触发器的月份。 可以是完整月份名称的列表或逗号分隔的字符串，例如 march 而不是 mar。 当type为monthlydow、monthly时可选。
随机延迟 字符串	随机添加到触发器开始时间的延迟时间。 当type为daily、monthlydow、monthly、time、weekly时可选。 采用 ISO 8601 持续时间格式P[n]Y[n]M[n]DT[n]H[n]M[n]S。
重复 字符串	允许您定义触发器的重复操作，该操作定义任务运行的频率以及在任务启动后重复重复模式的持续时间。 它包含以下键：duration、interval、stop_at_duration_end
持续时间 字符串	定义重复模式的持续时间。 该值采用 ISO 8601 持续时间格式P[n]Y[n]M[n]DT[n]H[n]M[n]S。 默认情况下，此项未设置，这意味着它将无限期地重复。
间隔 字符串	每次重新启动任务之间的时间量。 该值采用 ISO 8601 持续时间格式P[n]Y[n]M[n]DT[n]H[n]M[n]S。
在持续时间结束时停止 布尔值	在重复模式结束时是否停止正在运行的任务实例。 选项 否 是
在每月的最后一天运行 布尔值	布尔值，用于设置任务是否在每月的最后一天运行。 当type为monthly时可选。 选项 否 是
在每月的最后一周运行 布尔值	布尔值，用于设置任务是否在每月的最后一周运行。 当type为monthlydow时可选。 选项 否 是
开始边界 字符串	任务的开始时间，即使触发器满足其他开始条件，它也直到满足此时间才会启动。 如果您希望在一天中的上午 9 点运行任务，您仍然需要指定激活触发器的日期，您可以设置任何日期，甚至是过去的日期。 当type为daily、monthlydow、monthly、time、weekly时必需。 其余触发器类型可选。 采用 ISO 8601 日期时间格式YYYY-MM-DDThh:mm:ss。
状态更改 字符串 在 community.windows 1.6.0 中添加	允许您定义触发任务的终端服务器会话更改的类型。 当type=session_state_change时可选 选项 "控制台连接" "控制台断开连接" "远程连接" "远程断开连接" "会话锁定" "会话解锁"
订阅 字符串	仅用于type=event，并且是必需的。 标识触发事件的 XML 查询字符串。
类型 字符串 / 必需	触发器类型，此值控制需要哪些以下选项。 选项 "启动" "每日" "事件" "空闲" "登录" "每月星期几" "每月" "注册" "时间" "每周" "会话状态更改"
用户 ID 字符串	触发器将定位到的用户名。 当type为logon、session_state_change时可选。 可以是用户的用户名或 SID。 当type=logon并且希望组中的用户登录时触发器触发时，请将其保留为空，并将group设置为要触发的组。
周间隔 整数	要运行的周间隔，例如1表示每周，而2表示每隔一周。 当type=weekly时可选。
月份中的周 字符串	触发器的月份中的周。 可以是表示月份的第 1 到第 4 周的数字 1 到 4 的列表或逗号分隔的字符串。 当type=monthlydow时可选。
更新密码 布尔值	即使没有发生其他更改，是否更新密码。 当yes时，执行模块时将始终导致更改。 选项 否 true ← (默认)
用户名 别名：user 字符串	用于运行计划任务的用户。 在创建期间未指定的情况下，将默认为交互式令牌下的当前用户。 指定的用戶帐户必须具有SeBatchLogonRight登录权限，可以使用ansible.windows.win_user_right添加。
版本 字符串	任务的版本号。
wake_to_run 布尔值	任务运行时是否唤醒计算机。 选项 否 是

备注

注意

• 服务操作和触发器的选项名称和结构遵循RegisteredTask命名标准和要求。如果遇到任何问题，阅读本指南将很有帮助 https://msdn.microsoft.com/en-us/library/windows/desktop/aa382542.aspx。

• 通过将logon_type设置为password并省略密码参数可以使用组托管服务帐户 (gMSA)。有关 gMSA 的更多信息，请参阅 https://techcommunity.microsoft.com/t5/Core-Infrastructure-and-Security/Windows-Server-2012-Group-Managed-Service-Accounts/ba-p/255910

另请参阅

另请参阅

community.windows.win_scheduled_task_stat

获取有关 Windows 计划任务的信息。

ansible.windows.win_user_right

管理 Windows 用户权限。

示例

- name: Create a task to open 2 command prompts as SYSTEM
  community.windows.win_scheduled_task:
    name: TaskName
    description: open command prompt
    actions:
      - path: cmd.exe
        arguments: /c hostname
      - path: cmd.exe
        arguments: /c whoami
    triggers:
      - type: daily
        start_boundary: '2017-10-09T09:00:00'
    username: SYSTEM
    state: present
    enabled: true

- name: Create task to run a PS script as NETWORK service on boot
  community.windows.win_scheduled_task:
    name: TaskName2
    description: Run a PowerShell script
    actions:
      - path: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
        arguments: -ExecutionPolicy Unrestricted -NonInteractive -File C:\TestDir\Test.ps1
    triggers:
      - type: boot
    username: NETWORK SERVICE
    run_level: highest
    state: present

- name: Update Local Security Policy to allow users to run scheduled tasks
  ansible.windows.win_user_right:
    name: SeBatchLogonRight
    users:
      - LocalUser
      - DOMAIN\NetworkUser
    action: add

- name: Change above task to run under a domain user account, storing the passwords
  community.windows.win_scheduled_task:
    name: TaskName2
    username: DOMAIN\User
    password: Password
    logon_type: password

- name: Change the above task again, choosing not to store the password
  community.windows.win_scheduled_task:
    name: TaskName2
    username: DOMAIN\User
    logon_type: s4u

- name: Change above task to use a gMSA, where the password is managed automatically
  community.windows.win_scheduled_task:
    name: TaskName2
    username: DOMAIN\gMsaSvcAcct$
    logon_type: password

- name: Create task with multiple triggers
  community.windows.win_scheduled_task:
    name: TriggerTask
    path: \Custom
    actions:
      - path: cmd.exe
    triggers:
      - type: daily
      - type: monthlydow
    username: SYSTEM

- name: Set logon type to password but don't force update the password
  community.windows.win_scheduled_task:
    name: TriggerTask
    path: \Custom
    actions:
      - path: cmd.exe
    username: Administrator
    password: password
    update_password: false

- name: Disable a task that already exists
  community.windows.win_scheduled_task:
    name: TaskToDisable
    enabled: false

- name: Create a task that will be repeated every minute for five minutes
  community.windows.win_scheduled_task:
    name: RepeatedTask
    description: open command prompt
    actions:
      - path: cmd.exe
        arguments: /c hostname
    triggers:
      - type: registration
        repetition:
          interval: PT1M
          duration: PT5M
          stop_at_duration_end: true

- name: Create task to run a PS script in Windows 10 compatibility on boot with a delay of 1min
  community.windows.win_scheduled_task:
    name: TriggerTask
    path: \Custom
    actions:
      - path: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
        arguments: -ExecutionPolicy Unrestricted -NonInteractive -File C:\TestDir\Test.ps1
    triggers:
      - type: boot
        delay: PT1M
    username: SYSTEM
    compatibility: 4

作者

• Peter Mounce (@petemounce)

• Jordan Borean (@jborean93)

资源链接

• 问题跟踪器
• 代码库（源代码）
• 通信