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 布尔值	是否可以通过使用“运行”命令或上下文菜单启动任务。 选择 false true
allow_hard_terminate 布尔值	是否可以使用 TerminateProcess 终止任务。 选择 false true
author 字符串	任务的作者。
compatibility 整数	指示任务与哪个版本的任务计划程序兼容的整数值。 0 表示该任务与 AT 命令兼容。 1 表示该任务与任务计划程序 1.0（Windows Vista、Windows Server 2008 及更早版本）兼容。 2 表示该任务与任务计划程序 2.0（Windows Vista、Windows Server 2008）兼容。 3 表示该任务与任务计划程序 2.0（Windows 7、Windows Server 2008 R2）兼容。 4 表示该任务与任务计划程序 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 布尔值	如果计算机正在使用电池供电，是否不启动任务。 选择 false true
display_name 字符串	在任务计划程序 UI 中显示的用户/组的名称。
enabled 布尔值	是否启用该任务，该任务只能在 yes 时运行。 选择 false true
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 中隐藏任务。 选择 false true
logon_type 字符串	该任务将使用的登录方法。 password 表示密码将被存储，并且任务可以访问网络资源。 s4u 表示将使用现有的令牌运行任务，并且不会在任务中存储密码。这意味着无法访问网络或加密文件。 interactive_token 表示用户必须已经以交互方式登录，并且将在现有的交互式会话中运行。 group 表示该任务将作为一个组运行。 service_account 表示任务将以服务帐户（如 System、Local Service 或 Network Service）的身份运行。 选择 "none"（无） "password"（密码） "s4u"（S4U） "interactive_token"（交互式令牌） "group"（组） "service_account"（服务帐户） "token_or_password"（令牌或密码）
multiple_instances（多实例） 整数	一个整数，表示启动已在运行的任务时的行为。 0 将与该任务的现有实例并行启动一个新实例。 1 将等待该任务的其他实例运行完毕后再启动自身。 2 如果另一个实例正在运行，则不会启动新实例。 3 将停止该任务的其他实例并启动新实例。 选择 0 1 2 3
name（名称） 字符串 / 必需	计划任务的名称，不包括路径。
password（密码） 字符串	用于运行计划任务的用户帐户的密码。 在用户未登录的情况下运行任务时，需要此密码，但不包括内置服务帐户和组托管服务帐户 (gMSA)。 如果设置了此选项，除非 update_password 设置为 no 并且该服务不需要其他更改，否则将始终导致更改。
path 字符串	此任务将存储在其中的任务文件夹。 当 state=present 且该文件夹尚不存在时，将创建该文件夹。 当 state=absent 且该文件夹中没有剩余的任务时，将删除该文件夹。 默认值： "\\"
priority（优先级） 整数	任务的优先级级别 (0-10)。 创建新任务时，默认值为 7。 有关优先级级别的详细信息，请参阅 https://msdn.microsoft.com/en-us/library/windows/desktop/aa383512.aspx。
restart_count（重启次数） 整数	任务计划程序将尝试重启任务的次数。
restart_interval（重启间隔） 字符串	任务计划程序将尝试重启任务的时间。 如果设置此选项，则还必须设置 restart_count。 允许的最大时间为 31 天。 允许的最小时间为 1 分钟。 这是 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
run_level（运行级别） 别名: runlevel 字符串	用于运行任务的用户权限级别。 如果未指定，将使用有限权限创建任务。 选择 "limited"（受限） "highest"（最高）
run_only_if_idle（仅在空闲时运行） 布尔值	是否仅当计算机处于空闲状态时才运行任务。 选择 false true
run_only_if_network_available（仅在网络可用时运行） 布尔值	是否仅在网络可用时才运行任务。 选择 false true
source（源） 字符串	任务的来源。
start_when_available（可用时启动） 布尔值	是否可以在其计划时间过后随时启动任务。 选择 false true
state（状态） 字符串	当 state=present 时，将确保任务存在。 当 state=absent 时，将确保任务不存在。 选择 "absent"（不存在） "present"（存在） ← (默认)
stop_if_going_on_batteries（如果开始使用电池供电则停止） 布尔值	如果计算机开始使用电池供电，是否停止任务。 选择 false true
triggers（触发器） 列表 / 元素=字典	要为任务配置的触发器列表。 有关如何构造每个列表条目的详细信息，请参阅子选项。 此列表的顺序很重要，该模块将确保在修改任务时保持顺序。 有多种类型的触发器，有关触发器类型及其选项的列表，请参阅 https://msdn.microsoft.com/en-us/library/windows/desktop/aa383868.aspx。 下面列出的子选项并非所有触发器类型都必需，请阅读描述以了解更多详细信息。
days_of_month（月份中的天数） 字符串	触发器的月份中的天数，从 1 到 31。 如果要将触发器设置为任何月份的最后一天，请使用 run_on_last_day_of_month。 可以是天数列表或逗号分隔的字符串。 当 type=monthly 时为必需。
days_of_week（星期几） 字符串	触发器的星期几。 可以是完整星期几名称的列表或逗号分隔的字符串，例如 monday 而不是 mon。 当 type 为 weekly 时为必需。 当 type=monthlydow 时为可选。
delay（延迟） 字符串	触发器触发后延迟任务运行的时间。 当 type 为 boot、event、logon、registration、session_state_change 时为可选。 格式为 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
enabled 布尔值	是否将触发器设置为启用或禁用 在所有触发器类型中使用。 选择 false true
end_boundary（结束边界） 字符串	触发器被停用的结束时间。 格式为 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。
months_of_year（年份中的月份） 字符串	触发器的年份中的月份。 可以是完整月份名称的列表或逗号分隔的字符串，例如 march 而不是 mar。 当 type 为 monthlydow、monthly 时为可选。
random_delay（随机延迟） 字符串	随机添加到触发器启动时间的延迟时间。 当 type 为 daily、monthlydow、monthly、time、weekly 时为可选。 格式为 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。
repetition（重复） 字符串	允许您定义触发器的重复操作，该操作定义任务的运行频率以及任务启动后重复模式的重复时间。 它接受以下键：duration、interval、stop_at_duration_end
duration（持续时间） 字符串	定义模式重复的时间。 该值采用 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S。 默认情况下，未设置此值，这意味着它将无限期重复。
interval（间隔） 字符串	任务每次重启之间的时间量。 该值以 ISO 8601 持续时间格式 P[n]Y[n]M[n]DT[n]H[n]M[n]S 写入。
stop_at_duration_end（在持续时间结束时停止） 布尔值	是否在重复模式结束时停止正在运行的任务实例。 选择 false true
run_on_last_day_of_month（在每月最后一天运行） 布尔值	布尔值，设置任务是否在每月的最后一天运行。 当 type 为 monthly 时为可选。 选择 false true
run_on_last_week_of_month（在每月最后一周运行） 布尔值	布尔值，设置任务是否在每月的最后一周运行。 当 type 为 monthlydow 时为可选。 选择 false true
start_boundary（开始边界） 字符串	任务的开始时间，即使触发器满足其他启动条件，在满足此时间之前也不会启动。 如果您希望在某天上午 9 点运行任务，您仍然需要指定触发器激活的日期，您可以设置任何日期，即使是过去的日期。 当 type 为 daily、monthlydow、monthly、time、weekly 时为必需。 对于其余的触发器类型，此项是可选的。 格式为 ISO 8601 日期时间格式 YYYY-MM-DDThh:mm:ss。
state_change（状态更改） 字符串 在 community.windows 1.6.0 中添加	允许您定义触发任务的终端服务器会话更改类型。 当 type=session_state_change 时为可选 选择 "console_connect"（控制台连接） "console_disconnect"（控制台断开连接） "remote_connect"（远程连接） "remote_disconnect"（远程断开连接） "session_lock"（会话锁定） "session_unlock"（会话解锁）
subscription（订阅） 字符串	仅在 type=event 时使用，并且为必需。 标识触发触发器的事件的 XML 查询字符串。
type（类型） 字符串 / 必需	触发器类型，此值控制下面需要哪些选项。 选择 "boot"（启动） "daily"（每日） "event"（事件） "idle"（空闲） "logon"（登录） "monthlydow"（每月某天） "monthly"（每月） "registration"（注册） "time"（时间） "weekly"（每周） "session_state_change"（会话状态更改）
user_id 字符串	触发器将目标指向的用户名。 当 type 为 logon 或 session_state_change 时，此项为可选。 可以是用户名或用户的 SID。 当 type=logon 且您希望在组中的用户登录时触发触发器，请将此项留空，并将 group 设置为您希望触发的组。
weeks_interval 整数	运行的周期间隔，例如，1 表示每周，而 2 表示每隔一周。 当 type=weekly 时，此项为可选。
weeks_of_month 字符串	触发器触发的月份中的周数。 可以是数字 1 到 4 的列表或逗号分隔的字符串，分别代表该月的第一周到第四周。 当 type=monthlydow 时为可选。
update_password 布尔值	是否即使没有发生其他更改也更新密码。 当设置为 yes 时，执行该模块总会导致更改。 选择 false true ← (默认)
username 别名: user 字符串	运行计划任务的用户。 如果在创建期间未指定，则默认为当前用户（在交互式令牌下）。 指定的用户帐户必须具有 SeBatchLogonRight 登录权限，该权限可以使用 ansible.windows.win_user_right 添加。
version 字符串	任务的版本号。
wake_to_run 布尔值	当到达运行任务的时间时，任务是否会唤醒计算机。 选择 false true

备注

注意

• 服务操作和触发器的选项名称和结构遵循 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)

集合链接

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