本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 计划程序 CLI
<a name="scheduler-cli-4"></a>

利用 AWS 实例计划程序命令行界面（CLI），您可以配置计划和时段，并估算给定计划的成本节省。

## 先决条件
<a name="prerequisites"></a>

此解决方案中的 CLI 需要 Python 3.8\+ 及最新版本的 boto3。

## 凭据
<a name="credentials"></a>

要使用计划程序 CLI，您必须拥有 AWS CLI 的凭证。有关更多信息，请参阅《AWS CLI 用户指南》**中的[配置和凭证文件设置](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。

您的凭证必须具备以下权限：
+  `lambda:InvokeFunction`-在调度程序堆栈中调用该 InstanceSchedulerMain 函数，并从命令行更新计划程序配置数据库中的计划和周期信息
+  `cloudformation:DescribeStackResource`：用于从堆栈中检索 AWS Lambda 函数的物理资源 ID 以处理 CLI 请求

计划程序 CLI 发出的请求以及对应的响应将记录在 `AdminCliRequestHandler-yyyymmdd` 日志流中。

**注意**  
如果您使用 profile-name 参数指定一个配置文件，则所指定的该配置文件必须具备这些权限。有关 profile-name 参数的更多信息，请参阅[常见参数](#common-arguments)。

## 安装计划程序 CLI
<a name="install-the-scheduler-cli"></a>

1.  [下载](https://s3.amazonaws.com/solutions-reference/instance-scheduler-on-aws/latest/instance_scheduler_cli.zip)计划程序 CLI 包***（instance\_scheduler\_cli.zip）***，并将其放置在计算机上的某个目录中。
**重要**  
如果您未将该文件放入独立目录，再从该目录执行安装操作，安装过程将失败。

1. 将 zip 存档文件解压缩到其专属目录（instance\_scheduler\_cli）中。

1. 在存放解压后 CLI 包的同一目录中，将 scheduler-cli 安装到您的环境中：
**注意**  
Scheduler-CLI 需要 Python 3.8 或更高版本以及最新版本的 pip 和 boto3。如果您的本地计算机上尚未安装所有这些软件，请在尝试安装 Scheduler-CLI 之前，参考 [pip 的官方文档](https://pip.pypa.io/en/stable/getting-started/)以获取安装说明。

   ```
   pip install --no-index --find-links=instance_scheduler_cli instance_scheduler_cli
   ```

1. 使用以下命令验证是否已成功安装：

   ```
   scheduler-cli --help
   ```

**注意**  
如果您倾向于使用 [sdist of the CLI](https://s3.amazonaws.com/solutions-reference/instance-scheduler-on-aws/latest/instance_scheduler_cli-3.0.0.tar.gz)，也可通过上述相同流程安装它。

## 命令结构
<a name="command-structure"></a>

计划程序 CLI 在命令行中使用多部分结构。下一部分用于指定计划程序 CLI python 脚本。计划程序 CLI 包含用于指定要对时段和计划执行的操作的命令。可以通过命令行按任意顺序指定操作的特定参数。

```
scheduler-cli <command> <arguments>
```

## 常见参数
<a name="common-arguments"></a>

计划程序 CLI 支持以下参数，所有命令都可使用这些参数：


| 参数 | 说明 | 
| --- | --- | 
|  `--stack [replaceable]<stackname>`  | 计划程序堆栈的名称。<br /> **重要提示：**所有命令都需要使用此参数。 | 
|  `--region [replaceable]<regionname>`  | 将计划程序堆栈部署到的区域的名称。<br /> **注意：**当默认配置文件和凭证文件未安装到解决方案堆栈所在的同一区域时，您必须使用此参数。 | 
|  `--profile-name [replaceable] <profilename>`  | 用于运行命令的配置文件的名称。如果未指定配置文件名称，将使用默认配置文件。 | 
|  `--query`  | 控制命令输出的 JMESPath 表达式。有关控制输出的更多信息，请参阅《AWS CLI 用户指南》**中的[在 AWS CLI 中控制命令输出](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html)。 | 
|  `--help`  | 显示计划程序 CLI 的有效命令和参数。在将此参数与特定命令结合使用时，将显示该命令的有效子命令和参数。 | 
|  `--version`  | 显示计划程序 CLI 的版本号。 | 

## 可用命令
<a name="available-commands"></a>
+  [create-period](#create-period) 
+  [create-schedule](#create-schedule) 
+  [delete-period](#delete-period) 
+  [delete-schedule](#delete-schedule) 
+  [describe-periods](#describe-periods) 
+  [describe-schedules](#describe-schedules) 
+  [describe-schedule-usage](#describe-schedule-usage) 
+  [update-period](#update-period) 
+  [update-schedule](#update-schedule) 
+  [help](#help) 

## create-period
<a name="create-period"></a>

### 说明
<a name="create-period-description"></a>

创建时段。时段必须包含至少以下一个项目：`begintime`、`endtime`、`weekdays`、`months` 或 `monthdays`。

### 参数
<a name="create-period-arguments"></a>

 `--name`   
+ 时段的名称

  类型：字符串

  是否必需：是

 `--description`   
+ 时段的描述

  类型：字符串

  必需：否

 `--begintime`   
+ 运行时段的开始时间。如果未指定 `begintime` 和 `endtime`，则运行时段为 00:00-23:59。

  类型：字符串

  限制：`H:MM` 或 `HH:MM` 格式

  必需：否

 `--endtime`   
+ 运行时段的停止时间。如果未指定 `begintime` 和 `endtime`，则运行时段为 00:00-23:59。

  类型：字符串

  限制：`H:MM` 或 `HH:MM` 格式

  必需：否

 `--weekdays`   
+ 时段对应的星期几

  类型：字符串

  限制：缩写日期名称（mon）或数字（0）的逗号分隔列表。使用 - 指定范围。使用 / 指定每周的第 n 天。

  必需：否

 `--months`   
+ 时段的月份

  类型：字符串

  限制：缩写月份名称（jan）或数字（1）的逗号分隔列表。使用 - 指定范围。使用 / 指定每隔 n 个月。

  必需：否

 `--monthdays`   
+ 时段对应的月份日期

  类型：字符串

  限制：缩写月份名称（jan）或数字（1）的逗号分隔列表。使用 - 指定范围。使用 / 指定每月的第 n 天。

  必需：否

### 示例
<a name="create-period-example"></a>

```
$ scheduler-cli create-period --name "weekdays" --begintime 09:00 --endtime 18:00 --weekdays mon-fri --stack Scheduler
{
   "Period": {
      "Name": "weekdays",
      "Endtime": "18:00",
      "Type": "period",
      "Begintime": "09:00",
      "Weekdays": [
         "mon-fri"
      ]
   }
    }
```

## create-schedule
<a name="create-schedule"></a>

### 说明
<a name="create-schedule-description"></a>

创建计划。

### 参数
<a name="create-schedule-arguments"></a>

 `--name`   
+ 计划的名称

  类型：字符串

  是否必需：是

 `--description`   
+ 计划的描述

  类型：字符串

  必需：否

 `--enforced`   
+ 强制实施实例的计划状态

  必需：否

 `--use-metrics`   
+ 收集亚马逊 CloudWatch 指标

  必需：否

 `--periods`   
+ 计划的运行时段列表。如果指定了多个时段，则只要某个时段的条件判定为 `true`，解决方案就会启动实例。

  类型：字符串

  限制：时段的逗号分隔列表。使用 `<period-name>@[replaceable]<instance type>` 可指定时段的实例类型。例如 `weekdays@t2.large`。

  是否必需：是

 `--retain-running`   
+ 阻止解决方案在运行时段结束时停止实例（如果实例已在该运行时段开始前被手动启动）。

  必需：否

 `--ssm-maintenance-window`   
+ 将 AWS Systems Manager 维护时段作为运行时段添加到 Amazon EC2 实例计划中。

  类型：字符串

  必需：否

 `--do-not-stop-new-instances`   
+ 不在首次标记实例时将其停止（如果实例在运行时段之外运行）

  必需：否

 `--timezone`   
+ 计划将使用的时区

  类型：字符串数组

  必需：否（如果不使用此参数，则使用主解决方案堆栈中的默认时区。）

 `--use-maintenance-window`   
+ 将 Amazon RDS 维护时段作为运行时段添加到 Amazon RDS 实例计划，或将 AWS Systems Manager 维护时段作为运行时段添加到 Amazon EC2 实例计划

  类型：true/false

  必需：否（默认为 true）

### 示例
<a name="create-schedule-example"></a>

```
$ scheduler-cli create-schedule --name LondonOfficeHours --periods weekdays,weekends --timezone Europe/London --stack Scheduler
{
   "Schedule": {
      "Enforced": false,
      "Name": "LondonOfficeHours",
      "StopNewInstances": true,
      "Periods": [
         "weekends",
         "weekdays"
      ],
      "Timezone": "Europe/London",
      "Type": "schedule"
   }
}
```

## delete-period
<a name="delete-period"></a>

 `--name`   
+ 适用时段的名称

  类型：字符串

  是否必需：是

**重要**  
如果该时段已用于现有计划中，则必须先从这些计划中移除该时段，*然后* 才能将其删除。

 **示例** 

```
$ scheduler-cli delete-period --name weekdays --stack Scheduler
{
   "Period": "weekdays"
}
```

## delete-schedule
<a name="delete-schedule"></a>

### 说明
<a name="delete-schedule-description"></a>

删除现有计划

### 参数
<a name="delete-schedule-arguments"></a>

 `--name`   
+ 适用计划的名称

  类型：字符串

  是否必需：是

### 示例
<a name="delete-schedule-example"></a>

```
$ scheduler-cli delete-schedule --name LondonOfficeHours --stack Scheduler
{
   "Schedule": "LondonOfficeHours"
}
```

## describe-periods
<a name="describe-periods"></a>

### 说明
<a name="describe-periods-description"></a>

列出已为实例计划程序堆栈配置的时段

### 参数
<a name="describe-periods-arguments"></a>

 `--name`   
+ 要描述的特定时段的名称

  类型：字符串

  必需：否

### 示例
<a name="describe-periods-example"></a>

```
$ scheduler-cli describe-periods --stack Scheduler
{
   "Periods": [
      {
         "Name": "first-monday-in-quarter",
         "Months": [
            "jan/3"
         ],
         "Type": "period",
         "Weekdays": [
            "mon#1"
         ],
         "Description": "Every first Monday of each quarter"
      },
      {
         "Description": "Office hours",
         "Weekdays": [
            "mon-fri"
         ],
         "Begintime": "09:00",
         "Endtime": "17:00",
         "Type": "period",
         "Name": "office-hours"
      },

      {
         "Name": "weekdays",
         "Endtime": "18:00",
         "Type": "period",
         "Weekdays": [
            "mon-fri"
         ],
         "Begintime": "09:00"
      },
      {
         "Name": "weekends",
         "Type": "period",
         "Weekdays": [
            "sat-sun"
         ],
         "Description": "Days in weekend"
      }
   ]
}
```

## describe-schedules
<a name="describe-schedules"></a>

### 说明
<a name="describe-schedules-description"></a>

列出已为实例计划程序堆栈配置的计划。

### 参数
<a name="describe-schedules-arguments"></a>

 `--name`   
+ 要描述的特定计划的名称

  类型：字符串

  必需：否

### 示例
<a name="describe-schedules-example"></a>

```
$ scheduler-cli describe-schedules --stack Scheduler

{
   "Schedules": [
      {
         "OverrideStatus": "running",
         "Type": "schedule",
         "Name": "Running",
         "UseMetrics": false
      },
      {
         "Timezone": "UTC",
         "Type": "schedule",
         "Periods": [
            "working-days@t2.micro",
            "weekends@t2.nano"
         ],
         "Name": "scale-up-down"
      },
      {
         "Timezone": "US/Pacific",
         "Type": "schedule",
         "Periods": [
            "office-hours"
         ],
         "Name": "seattle-office-hours"
      },
      {
         "OverrideStatus": "stopped",
         "Type": "schedule",
         "Name": "stopped",
         "UseMetrics": true
      }
   ]
}
```

## describe-schedule-usage
<a name="describe-schedule-usage"></a>

### 说明
<a name="describe-schedule-usage-description"></a>

列出计划内运行的所有时段，并计算实例的计费时长（以小时为单位）。使用此命令可模拟计划以计算潜在的成本节省，以及创建或更新计划后的运行时段。

### 参数
<a name="describe-schedule-usage-arguments"></a>

 `--name`   
+ 适用计划的名称

  类型：字符串

  是否必需：是

 `--startdate`   
+ 用于计算的时段的开始日期。默认日期为当前日期。

  类型：字符串

  必需：否

 `--enddate`   
+ 用于计算的时段的结束日期。默认日期为当前日期。

  类型：字符串

  必需：否

### 示例
<a name="describe-schedule-usage-example"></a>

```
$ scheduler-cli describe-schedule-usage --stack InstanceScheduler --name seattle-office-hours
{
   "Usage": {
      "2017-12-04": {
         "BillingHours": 8,
         "RunningPeriods": {
            "Office-hours": {
               "Begin": "12/04/17 09:00:00",
               "End": "12/04/17 17:00:00",
               "BillingHours": 8,
               "BillingSeconds": 28800
            }
         },
         "BillingSeconds": 28800
      }
   },
   "Schedule": "seattle-office-hours"
```

## update-period
<a name="update-period"></a>

### 说明
<a name="update-period-description"></a>

更新现有时段

### 参数
<a name="update-period-arguments"></a>

`update-period` 命令支持与 `create-period` 命令相同的参数。有关参数的更多信息，请参阅 [create period 命令](#create-period)。

**重要**  
如果您未指定参数，则将从时段中移除该参数。

## update-schedule
<a name="update-schedule"></a>

### 说明
<a name="update-schedule-description"></a>

删除现有计划

### 参数
<a name="update-schedule-arguments"></a>

`update-schedule` 命令支持与 `create-schedule` 命令相同的参数。有关参数的更多信息，请参阅 [create schedule 命令](#create-schedule)。

**重要**  
如果您未指定参数，则将从计划中移除该参数。

## help
<a name="help"></a>

### 说明
<a name="help-description"></a>

显示计划程序 CLI 的有效命令和参数的列表。

### 示例
<a name="help-example"></a>

```
$ scheduler-cli --help
usage: scheduler-cli [-h] [--version]
                     {create-period,create-schedule,delete-period,delete-schedule,describe-periods,describe-schedule-usage,describe-schedules,update-period,update-schedule}
                     ...

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

subcommands:
  Valid subcommands

  {create-period,create-schedule,delete-period,delete-schedule,describe-periods,describe-schedule-usage,describe-schedules,update-period,update-schedule}
                        Commands help
    create-period       Creates a period
    create-schedule     Creates a schedule
    delete-period       Deletes a period
    delete-schedule     Deletes a schedule
    describe-periods    Describes configured periods
    describe-schedule-usage
                        Calculates periods and billing hours in which
                        instances are running
    describe-schedules  Described configured schedules
    update-period       Updates a period
    update-schedule     Updates a schedule
```

在将 `--help` 参数与特定命令结合使用时，此参数将显示该命令的有效子命令和参数。

### 特定命令示例
<a name="help-example-specific-command"></a>

```
$ scheduler-cli describe-schedules --help
usage: scheduler-cli describe-schedules [-h] [--name NAME] [--query QUERY]
                                        [--region REGION] --stack STACK

optional arguments:
  -h, --help         show this help message and exit
  --name NAME        Name of the schedule
  --query QUERY      JMESPath query to transform or filter the result
  --region REGION    Region in which the Instance Scheduler stack is
                        deployed
  --stack STACK, -s STACK
                     Name of the Instance Scheduler stack
```