本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWSTOE 组件管理器支持的操作模块
映像构建服务（例如 EC2 Image Builder）使用 AWSTOE 操作模块来帮助配置用于构建和测试自定义机器映像的 EC2 实例。本节介绍常用 AWSTOE 操作模块的功能以及如何配置它们，包括示例。
组件是用纯文本 YAML 文档编写的。有关文档语法的更多信息，请参阅 [使用 AWSTOE 组件文档框架创建自定义组件](toe-use-documents.md)。
**注意**
所有操作模块在运行时都使用与 Systems Manager 代理相同的帐户，即 Linux 上的 `root` 和 Windows 上的 `NT Authority\SYSTEM`。
以下交叉引用按操作模块执行的操作类型对其进行了分类。
**一般执行**
+ [Assert（Linux、Windows、macOS）](#action-modules-assertion)
+ [ExecuteBash （Linux、macOS）](#action-modules-executebash)
+ [ExecuteBinary （Linux、Windows、macOS）](#action-modules-executebinary)
+ [ExecuteDocument （Linux、Windows、macOS）](#action-modules-executedocument)
+ [ExecutePowerShell （视窗）](#action-modules-executepowershell)
**文件下载与上传**
+ [S3Download（Linux、Windows、macOS）](#action-modules-s3download)
+ [S3Upload（Linux、Windows、macOS）](#action-modules-s3upload)
+ [WebDownload （Linux、Windows、macOS）](#action-modules-webdownload)
**文件系统操作**
+ [AppendFile （Linux、Windows、macOS）](#action-modules-appendfile)
+ [CopyFile （Linux、Windows、macOS）](#action-modules-copyfile)
+ [CopyFolder （Linux、Windows、macOS）](#action-modules-copyfolder)
+ [CreateFile （Linux、Windows、macOS）](#action-modules-createfile)
+ [CreateFolder （Linux、Windows、macOS）](#action-modules-createfolder)
+ [CreateSymlink （Linux、Windows、macOS）](#action-modules-createsymlink)
+ [DeleteFile （Linux、Windows、macOS）](#action-modules-deletefile)
+ [DeleteFolder （Linux、Windows、macOS）](#action-modules-deletefolder)
+ [ListFiles （Linux、Windows、macOS）](#action-modules-listfiles)
+ [MoveFile （Linux、Windows、macOS）](#action-modules-movefile)
+ [MoveFolder （Linux、Windows、macOS）](#action-modules-movefolder)
+ [ReadFile （Linux、Windows、macOS）](#action-modules-readfile)
+ [SetFileEncoding （Linux、Windows、macOS）](#action-modules-setfileencoding)
+ [SetFileOwner （Linux、Windows、macOS）](#action-modules-setfileowner)
+ [SetFolderOwner （Linux、Windows、macOS）](#action-modules-setfolderowner)
+ [SetFilePermissions （Linux、Windows、macOS）](#action-modules-setfilepermissions)
+ [SetFolderPermissions （Linux、Windows、macOS）](#action-modules-setfolderpermissions)
**软件安装操作**
+ [InstallMSI (Windows)](#action-modules-install-msi)
+ [UninstallMSI (Windows)](#action-modules-uninstall-msi)
**系统操作**
+ [Reboot（Linux、Windows）](#action-modules-reboot)
+ [SetRegistry （视窗）](#action-modules-setregistry)
+ [UpdateOS（Linux、Windows）](#action-modules-updateos)
## 通用执行模块
下一部分详细介绍了运行命令和控制执行工作流的操作模块。
**Topics**
+ [Assert（Linux、Windows、macOS）](#action-modules-assertion)
+ [ExecuteBash （Linux、macOS）](#action-modules-executebash)
+ [ExecuteBinary （Linux、Windows、macOS）](#action-modules-executebinary)
+ [ExecuteDocument （Linux、Windows、macOS）](#action-modules-executedocument)
+ [ExecutePowerShell （视窗）](#action-modules-executepowershell)
### Assert（Linux、Windows、macOS）
**Assert** 操作模块使用[比较运算符](toe-comparison-operators.md)或[逻辑运算符](toe-logical-operators.md)作为输入进行值比较。运算符表达式的结果（true 或 false）表示步骤的总体成功或失败状态。
如果比较或逻辑运算符表达式的计算结果为 `true`，则该步骤将标记为 `Success`。否则，该步骤将标记为 `Failed`。如果步骤失败，则 `onFailure` 参数决定步骤的结果。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| input | 包含单个比较运算符或逻辑运算符。注意，逻辑运算符可以包含多个比较运算符。 | 这不是固定不变的，具体取决于操作人员 | 是 |
**输入示例：使用 `stringEquals` 比较运算符进行简单比较**
此示例的计算结果为 `true`。
```
- name: StringComparison
action: Assert
inputs:
stringEquals: '2.1.1'
value: '{{ validate.ApplicationVersion.outputs.stdout }}'
```
**输入示例：使用 `patternMatches` 比较运算符的正则表达式比较**
这些示例的计算结果均为 `true`。
```
- name: Letters only
action: Assert
inputs:
patternMatches: '^[a-zA-Z]+$'
value: 'ThisIsOnlyLetters'
- name: Letters and spaces only
action: Assert
inputs:
patternMatches: '^[a-zA-Z\s]+$'
value: 'This text contains spaces'
- name: Numbers only
action: Assert
inputs:
patternMatches: '^[0-9]+$'
value: '1234567890'
```
**输入示例：使用逻辑运算符和链式变量的嵌套比较**
以下示例演示了使用逻辑运算符和链式变量执行嵌套比较。如果以下任一条件为 true，则 `Assert` 的计算结果为 `true`：
+ `ApplicationVersion` 大于 `2.0` 并且 `CPUArchitecture` 等于 `arm64`。
+ `CPUArchitecture` 等于 `x86_64`。
```
- name: NestedComparisons
action: Assert
inputs:
or: # <- first level deep
- and: # <- second level deep
- numberGreaterThan: 2.0 # <- third level deep
value: '{{ validate.ApplicationVersion.outputs.stdout }}'
- stringEquals: 'arm64'
value: '{{ validate.CPUArchitecture.outputs.stdout }}'
- stringEquals: 'x86_64'
value: '{{ validate.CPUArchitecture.outputs.stdout }}'
```
**输出**：
`Assert` 的输出表示步骤的成功或失败。
### ExecuteBash （Linux、macOS）
**ExecuteBash**操作模块允许您使用内联 shell 代码/命令运行 bash 脚本。该模块支持 Linux。
您在命令块中指定的所有命令和指令都将转换为文件（例如 `input.sh`）并使用 bash Shell 执行。Shell 文件的执行结果是退出代码步骤。
如果脚本退出时退出代码为，则该**ExecuteBash**模块会处理系统重新启动。`194`在启动后，该应用程序执行以下操作之一：
+ 如果是由 Systems Manager 代理执行的，该应用程序将向调用方返回退出代码。Systems Manager 代理处理系统重启并运行启动重启的步骤，如[从脚本重启托管实例](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。
+ 该应用程序保存当前 `executionstate`，配置重新启动触发器以重新执行该应用程序，然后重新启动系统。
在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| commands | 包含根据 bash 语法执行的指令或命令列表。允许使用多行 YAML。 | 列表 | 是 |
**输入示例：重启前后**
```
name: ExitCode194Example
description: This shows how the exit code can be used to restart a system with ExecuteBash
schemaVersion: 1.0
phases:
- name: build
steps:
- name: RestartTrigger
action: ExecuteBash
inputs:
commands:
- |
REBOOT_INDICATOR=/var/tmp/reboot-indicator
if [ -f "${REBOOT_INDICATOR}" ]; then
echo 'The reboot file exists. Deleting it and exiting with success.'
rm "${REBOOT_INDICATOR}"
exit 0
fi
echo 'The reboot file does not exist. Creating it and triggering a restart.'
touch "${REBOOT_INDICATOR}"
exit 194
```
**Output**
| 字段 | 描述 | Type |
| --- | --- | --- |
| stdout | 命令执行的标准输出。 | 字符串 |
如果您执行重新引导，并返回退出代码 `194` 以作为操作模块的一部分，构建将在启动重新引导的同一操作模块步骤处继续执行。如果执行重新引导而没有退出代码，构建过程可能会失败。
**输出示例：重启前（首次按照文档）**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**输出示例：重启后（第二次按照文档）**
```
{
“stdout”: “The reboot file exists. Deleting it and exiting with success."
}
```
### ExecuteBinary （Linux、Windows、macOS）
**ExecuteBinary**操作模块允许您使用命令行参数列表运行二进制文件。
如果二进制文件退出时退出代码为 `194` (Linux) 或 `3010` (Windows)，则该**ExecuteBinary**模块会处理系统的重新启动。在触发后，该应用程序执行以下操作之一：
+ 如果是由 Systems Manager 代理执行的，该应用程序将向调用方返回退出代码。Systems Manager 代理负责系统重启并运行启动重启的步骤，如[从脚本重启托管实例](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。
+ 该应用程序保存当前 `executionstate`，配置重新启动触发器以重新执行该应用程序，然后重新启动系统。
在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| path | 要执行的二进制文件的路径。 | 字符串 | 是 |
| arguments | 包含在运行二进制文件时使用的命令行参数列表。 | 字符串列表 | 否 |
**输入示例：安装 .NET**
```
- name: "InstallDotnet"
action: ExecuteBinary
inputs:
path: C:\PathTo\dotnet_installer.exe
arguments:
- /qb
- /norestart
```
**Output**
| 字段 | 描述 | Type |
| --- | --- | --- |
| stdout | 命令执行的标准输出。 | 字符串 |
**输出示例**
```
{
"stdout": "success"
}
```
### ExecuteDocument （Linux、Windows、macOS）
**ExecuteDocument**操作模块增加了对嵌套组件文档的支持，从一个文档中运行多个组件文档。 AWSTOE 验证运行时在输入参数中传递的文档。
**限制**
+ 此操作模块运行一次，不允许重试，也没有设置超时限制的选项。 **ExecuteDocument**设置以下默认值，如果您尝试更改这些值，则会返回错误。
+ `timeoutSeconds`: -1
+ `maxAttempts`：1
**注意**
您可以将这些值留空，并 AWSTOE 使用默认值。
+ 文档可以嵌套，最多可嵌套三层，不得超过此限制。三个嵌套级别转换为四个文档级别，因为顶层不是嵌套的。在这种情况下，最低级别的文档不得调用任何其他文档。
+ 不允许循环执行组件文档。任何在循环结构之外调用自身文档，或者调用当前执行链中调用更高层的文档，都会引发循环，从而引发无限循环。当检测到循环执行时， AWSTOE 会停止执行并记录失败。
![\[ExecuteDocument 操作模块的嵌套级别限制。\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/images/toe-component-document-nesting.png)
如果组件文档尝试自行运行，或者尝试运行当前执行链中更高层的任何组件文档，执行将会失败。
**输入**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| document | 组件文档的路径。有效选项包括： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 字符串 | 是 |
| document-s3-bucket-owner | S3 存储桶所有者的账户 ID，用于存储组件文档的 S3 存储桶。*（如果您在组件文档 URIs 中使用 S3，则建议使用。）* | 字符串 | 否 |
| phases | 组件文件中要运行的阶段已用逗号分隔的列表来表示。如果未指定任何阶段，将运行所有阶段。 | 字符串 | 否 |
| parameters | 在运行时作为键值对传递到组件文档的输入参数。 | 参数映射列表 | 否 |
**参数映射输入**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| name | 要传递给**ExecuteDocument**操作模块正在运行的组件文档的输入参数的名称。 | 字符串 | 是 |
| value | 输入参数的值。 | 字符串 | 是 |
**输入示例**
以下示例显示了组件文档的输入变体，具体取决于您的安装路径。
**输入示例：本地文档路径**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: Sample-1.yaml
phases: build
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**输入示例：S3 URI 为文档路径**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: s3://my-bucket/Sample-1.yaml
document-s3-bucket-owner: 123456789012
phases: build,validate
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**输入示例：EC2 Image Builder 组件 ARN 为文档路径**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: arn:aws:imagebuilder:us-west-2:aws:component/Sample-Test/1.0.0
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**使用 ForEach 循环运行文档**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
loop:
name: 'myForEachLoop'
forEach:
- Sample-1.yaml
- Sample-2.yaml
inputs:
document: "{{myForEachLoop.value}}"
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**使用 For 循环运行文档**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
loop:
name: 'myForLoop'
for:
start: 1
end: 2
updateBy: 1
inputs:
document: "Sample-{{myForLoop.value}}.yaml"
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**Output**
AWSTOE 创建`detailedoutput.json`每次运行时都调用的输出文件。该文件包含运行时调用的每个组件文档的每个阶段和步骤的详细信息。对于**ExecuteDocument**操作模块，您可以在`outputs`字段中找到简短的运行时摘要，以及有关该模块在其中运行的阶段、步骤和文档的详细信息`detailedOutput`。
```
{
\"executedStepCount\":1,\"executionId\":\"97054e22-06cc-11ec-9b14-acde48001122\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"
}",
```
每个组件文档的输出摘要对象都包含以下详细信息以及示例值，如下所示：
+ executedStepCount“:1
+ "executionId": "12345a67-89bc-01de-2f34-abcd56789012"
+ failedStepCount“: 0
+ "failureMessage": ""
+ “ignoredFailedStep计数”: 0
+ "logUrl": ""
+ "status": "success"
**输出示例**
以下示例显示了发生嵌套执行时**ExecuteDocument**操作模块的输出。在此示例中，`main.yaml` 组件文档成功运行了 `Sample-1.yaml` 组件文档。
```
{
"executionId": "12345a67-89bc-01de-2f34-abcd56789012",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"documents": [
{
"name": "",
"filePath": "main.yaml",
"status": "success",
"description": "",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"phases": [
{
"name": "build",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"steps": [
{
"name": "ExecuteNestedDocument",
"status": "success",
"failureMessage": "",
"timeoutSeconds": -1,
"onFailure": "Abort",
"maxAttempts": 1,
"action": "ExecuteDocument",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"inputs": "[{\"document\":\"Sample-1.yaml\",\"document-s3-bucket-owner\":\"\",\"phases\":\"\",\"parameters\":null}]",
"outputs": "[{\"executedStepCount\":1,\"executionId\":\"98765f43-21ed-09cb-8a76-fedc54321098\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"}]",
"loop": null,
"detailedOutput": [
{
"executionId": "98765f43-21ed-09cb-8a76-fedc54321098",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"documents": [
{
"name": "",
"filePath": "Sample-1.yaml",
"status": "success",
"description": "",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"phases": [
{
"name": "build",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"steps": [
{
"name": "ExecuteBashStep",
"status": "success",
"failureMessage": "",
"timeoutSeconds": 7200,
"onFailure": "Abort",
"maxAttempts": 1,
"action": "ExecuteBash",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"inputs": "[{\"commands\":[\"echo \\\"Hello World!\\\"\"]}]",
"outputs": "[{\"stdout\":\"Hello World!\"}]",
"loop": null,
"detailedOutput": null
}]
}]
}]
}]
}]
}]
}]
}
```
### ExecutePowerShell （视窗）
**ExecutePowerShell**操作模块允许您使用内联 shell 代码/命令运行 PowerShell 脚本。该模块支持 Windows 平台和 Windows PowerShell。
命令块中 commands/instructions 指定的所有内容都将转换为脚本文件（例如`input.ps1`），并使用 Windows 运行PowerShell。Shell 文件的执行结果是退出代码。
如果 shell 命令退出时退出代码为，则该**ExecutePowerShell**模块将处理系统重新启动。`3010`在启动后，该应用程序执行以下操作之一：
+ 如果由 Systems Manager 代理运行，则将退出代码交给调用者。Systems Manager 代理处理系统重启并运行启动重启的步骤，如[从脚本重启托管实例](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。
+ 保存当前 `executionstate`，配置重新启动触发器以重新运行该应用程序，然后重新引导系统。
在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| commands | 包含要按照PowerShell 语法运行的指令或命令的列表。允许使用多行 YAML。 | 字符串列表 | 可以。必须指定 `commands` 或 `file`，但不能同时指定。 |
| file | 包含 PowerShell 脚本文件的路径。 PowerShell 将使用-file命令行参数对这个文件运行。路径必须指向 .ps1 文件。 | 字符串 | 可以。必须指定 `commands` 或 `file`，但不能同时指定。 |
**输入示例：重启前后**
```
name: ExitCode3010Example
description: This shows how the exit code can be used to restart a system with ExecutePowerShell
schemaVersion: 1.0
phases:
- name: build
steps:
- name: RestartTrigger
action: ExecutePowerShell
inputs:
commands:
- |
$rebootIndicator = Join-Path -Path $env:SystemDrive -ChildPath 'reboot-indicator'
if (Test-Path -Path $rebootIndicator) {
Write-Host 'The reboot file exists. Deleting it and exiting with success.'
Remove-Item -Path $rebootIndicator -Force | Out-Null
[System.Environment]::Exit(0)
}
Write-Host 'The reboot file does not exist. Creating it and triggering a restart.'
New-Item -Path $rebootIndicator -ItemType File | Out-Null
[System.Environment]::Exit(3010)
```
**Output**
| 字段 | 描述 | Type |
| --- | --- | --- |
| stdout | 命令执行的标准输出。 | 字符串 |
如果您执行重新引导，并返回退出代码 `3010` 以作为操作模块的一部分，构建将在启动重新引导的同一操作模块步骤处继续执行。如果执行重新引导而没有退出代码，构建过程可能会失败。
**输出示例：重启前（首次按照文档）**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**输出示例：重启后（第二次按照文档）**
```
{
“stdout”: “The reboot file exists. Deleting it and exiting with success."
}
```
## 文件下载与上传模块
下一节详细介绍了上传或下载文件的操作模块。
**Topics**
+ [S3Download（Linux、Windows、macOS）](#action-modules-s3download)
+ [S3Upload（Linux、Windows、macOS）](#action-modules-s3upload)
+ [WebDownload （Linux、Windows、macOS）](#action-modules-webdownload)
### S3Download（Linux、Windows、macOS）
使用 `S3Download` 操作模块，您可以将 Amazon S3 对象或一组对象下载到您使用 `destination` 路径指定的本地文件或文件夹。如果指定位置已存在任何文件，且 `overwrite` 标志设置为正确，则 `S3Download` 会覆盖该文件。
`source` 位置可以指向 Amazon S3 中的特定对象，也可以使用带有星号通配符 (`*`) 的键前缀，以下载一组与键前缀路径匹配的对象。当您在 `source` 位置指定键前缀时，`S3Download` 操作模块会下载与该前缀匹配的所有内容（包括文件和文件夹）。确保键前缀以正斜杠结尾，后跟星号 (`/*`)，以下载与该前缀匹配的所有内容。例如：`s3://my-bucket/my-folder/*`。
如果在下载过程中对指定键前缀的 `S3Download` 操作失败，文件夹内容不会回滚到失败之前的状态。目标文件夹将保持失败时的状态。
**支持的使用案例**
`S3Download` 操作模块支持以下案例：
+ Amazon S3 对象将下载到下载路径中指定的本地文件夹。
+ Amazon S3 对象（在 Amazon S3 文件路径中带有键前缀）将下载到指定的本地文件夹，该文件夹以递归方式将所有与键前缀匹配的 Amazon S3 对象复制到本地文件夹。
**IAM 要求**
与实例配置文件关联的 IAM 角色必须具有运行 `S3Download` 操作模块的权限。必须将以下 IAM 角色策略附加到与实例配置文件关联的 IAM 角色：
+ **单个文件**：`s3:GetObject`反对 bucket/object （例如，`arn:aws:s3:::BucketName/*`）。
+ **多个文件**：`s3:ListBucket`针对 bucket/object （例如，`arn:aws:s3:::BucketName`）和`s3:GetObject`反对 bucket/object （例如`arn:aws:s3:::BucketName/*`）。
**Input**
| Key | 说明 | Type | 必需 | 默认 |
| --- | --- | --- | --- | --- |
| `source` | Amazon S3 存储桶为下载源。您可以指定特定对象的路径，也可以使用键前缀（以正斜杠结尾，后跟星号通配符 (`/*`) 来下载一组与键前缀匹配的对象。 | 字符串 | 是 | 不适用 |
| `destination` | 下载 Amazon S3 对象的本地路径。要下载单个文件，您必须将文件名指定为路径的一部分。例如 `/myfolder/package.zip`。 | 字符串 | 是 | 不适用 |
| `expectedBucketOwner` | `source` 路径中提供的存储桶的预期拥有者账户 ID。我们建议您验证源中指定的 Amazon S3 存储桶的所有权。 | 字符串 | 否 | 不适用 |
| `overwrite` | 设置为正确时，如果指定本地路径的目标文件夹中已存在同名文件，下载文件将覆盖本地文件。如果设置为错误，可避免本地系统上的现有文件被覆盖，并且操作模块会因下载错误而失败。 例如，`Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.` | 布尔值 | 否 | true |
**注意**
对于以下示例，可以将 Windows 文件夹路径替换为 Linux 路径。例如，可以将 `C:\myfolder\package.zip` 替换为 `/myfolder/package.zip`。
**输入示例：将 Amazon S3 对象复制到本地文件**
以下示例说明了如何将 Amazon S3 对象复制到本地文件。
```
- name: DownloadMyFile
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
overwrite: false
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
overwrite: true
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
```
**输入示例：将具有键前缀的 Amazon S3 存储桶中的所有 Amazon S3 对象复制到本地文件夹**
下面的示例展示了如何将 Amazon S3 存储桶中带有键前缀的所有 Amazon S3 对象复制到本地文件夹。Amazon S3 没有文件夹概念，因此，将复制与键前缀匹配的所有对象。最大可下载数量为 1000。
```
- name: MyS3DownloadKeyprefix
action: S3Download
maxAttempts: 3
inputs:
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
overwrite: false
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
overwrite: true
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
```
**Output**
无。
### S3Upload（Linux、Windows、macOS）
使用 **S3Upload** 操作模块可以将文件从源文件/文件夹上传到某个 Amazon S3 位置。您可以在源位置指定的路径中使用通配符 (`*`)，以上传路径与通配符模式匹配的所有文件。
如果递归 **S3Upload** 操作失败，已上传的任何文件都将保留在目标 Amazon S3 存储桶中。
**支持的使用案例**
+ 将本地文件上传到 S3 对象。
+ 将文件夹中的本地文件（使用通配符）上传到 Amazon S3 键前缀。
+ 将本地文件夹（必须将 `recurse` 设置为 `true`）复制到 Amazon S3 键前缀。
**IAM 要求**
与实例配置文件关联的 IAM 角色必须具有运行 `S3Upload` 操作模块的权限。必须将以下 IAM 策略附加到与实例配置文件关联的 IAM 角色。该策略必须向目标 Amazon S3 存储桶授予 `s3:PutObject` 权限。例如，`arn:aws:s3:::BucketName/*`）。
**Input**
| Key | 说明 | Type | 必需 | 默认 |
| --- | --- | --- | --- | --- |
| `source` | files/folders 源所在的本地路径。`source` 支持星号通配符 (`*`)。 | 字符串 | 是 | 不适用 |
| `destination` | 上传源文件/文件夹的目标 Amazon S3 存储桶的路径。 | 字符串 | 是 | 不适用 |
| `recurse` | 如果设置为 `true`，则递归执行 **S3Upload**。 | 字符串 | 否 | `false` |
| `expectedBucketOwner` | 目标路径中指定的 Amazon S3 存储桶的预期所有者账户 ID。我们建议您验证目标中指定的 Amazon S3 存储桶的所有权。 | 字符串 | 否 | 不适用 |
**输入示例：将本地文件复制到 Amazon S3 对象**
以下示例说明了如何将本地文件复制到 Amazon S3 对象。
```
- name: MyS3UploadFile
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\package.zip
destination: s3://amzn-s3-demo-destination-bucket/path/to/package.zip
expectedBucketOwner: 123456789022
```
**输入示例：将具有键前缀的 Amazon S3 存储桶中的所有文件复制到本地文件夹**
以下示例展示了如何将本地文件夹中的所有文件复制到带有键前缀的 Amazon S3 存储桶中。该示例不会复制子文件夹或其内容，因为未指定 `recurse`，并且它默认为 `false`。
```
- name: MyS3UploadMultipleFiles
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\*
destination: s3://amzn-s3-demo-destination-bucket/path/to/
expectedBucketOwner: 123456789022
```
**输入示例：将所有文件和文件夹从本地文件夹递归复制到 Amazon S3 存储桶**
以下示例展示了如何将所有文件和文件夹从本地文件夹递归复制到带有键前缀的 Amazon S3 存储桶中。
```
- name: MyS3UploadFolder
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\*
destination: s3://amzn-s3-demo-destination-bucket/path/to/
recurse: true
expectedBucketOwner: 123456789022
```
**Output**
无。
### WebDownload （Linux、Windows、macOS）
**WebDownload**操作模块允许您通过 HTTP/HTTPS 协议从远程位置下载文件和资源（*建议使用 HTTPS*）。对下载数量或大小没有限制。该模块处理重试和指数回退逻辑。
根据用户输入，每次下载操作最多可尝试 5 次。这些尝试与 `steps` 文档的 `maxAttempts` 字段中指定的尝试不同，而是与操作模块失败有关。
此操作模块隐式处理重定向。除 `200` 外，所有 HTTP 状态代码都会引发错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 |
| --- | --- | --- | --- | --- |
| source | 有效的 HTTP/HTTPS 网址（建议使用 HTTPS），它符合 RFC 3986 标准。允许使用链式表达式。 | 字符串 | 是 | 不适用 |
| destination | 本地系统上的绝对或相对文件或文件夹路径。文件夹路径必须以 / 结尾。如果文件夹路径不以 / 结尾，将被视为文件路径。该模块会创建成功下载所需的任何文件或文件夹。允许使用链式表达式。 | 字符串 | 是 | 不适用 |
| overwrite | 启用后，下载的文件或资源将覆盖本地系统上的任何现有文件。如果未启用，则不会覆盖本地系统上的任何现有文件，并且操作模块会因错误而失败。启用覆盖并指定了校验和及算法后，只有在任何先前存在的文件的校验和与哈希值不匹配时，操作模块才会下载文件。 | 布尔值 | 否 | true |
| checksum | 当您指定校验和时，校验和会与使用提供的算法生成的已下载文件的哈希值进行比对。要启用文件验证，必须同时提供校验和与算法。允许使用链式表达式。 | 字符串 | 否 | 不适用 |
| algorithm | 用于计算校验和的算法。选项包括MD5、 SHA1 SHA256、和 SHA512。要启用文件验证，必须同时提供校验和与算法。允许使用链式表达式。 | 字符串 | 否 | 不适用 |
| ignoreCertificateErrors | 启用后，SSL 证书验证会被忽略。 | 布尔值 | 否 | false |
**Output**
| 键名称 | 说明 | Type |
| --- | --- | --- |
| destination | 以换行符分隔的字符串，指定了存储已下载文件或资源的目标路径。 | 字符串 |
**输入示例：将远程文件下载到本地目标**
```
- name: DownloadRemoteFile
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: C:\testfolder\package.zip
```
**输出**：
```
{
"destination": "C:\\testfolder\\package.zip"
}
```
**输入示例：将多个远程文件下载到多个本地目标**
```
- name: DownloadRemoteFiles
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: /tmp/java14_renamed.zip
- source: https://testdomain/path/to/java14.zip
destination: /tmp/create_new_folder_and_add_java14_as_zip/
```
**输出**：
```
{
"destination": "/tmp/create_new_folder/java14_renamed.zip\n/tmp/create_new_folder_and_add_java14_as_zip/java14.zip"
}
```
**输入示例：下载一个远程文件而不覆盖本地目标，然后下载另一个带有文件验证功能的远程文件**
```
- name: DownloadRemoteMultipleProperties
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: C:\create_new_folder\java14_renamed.zip
overwrite: false
- source: https://testdomain/path/to/java14.zip
destination: C:\create_new_folder_and_add_java14_as_zip\
checksum: ac68bbf921d953d1cfab916cb6120864
algorithm: MD5
overwrite: true
```
**输出**：
```
{
"destination": "C:\\create_new_folder\\java14_renamed.zip\nC:\\create_new_folder_and_add_java14_as_zip\\java14.zip"
}
```
**输入示例：下载远程文件并忽略 SSL 认证验证**
```
- name: DownloadRemoteIgnoreValidation
action: WebDownload
maxAttempts: 3
inputs:
- source: https://www.bad-ssl.com/resource
destination: /tmp/downloads/
ignoreCertificateErrors: true
```
**输出**：
```
{
"destination": "/tmp/downloads/resource"
}
```
## 文件系统操作模块
下一节详细介绍了执行文件系统操作的操作模块。
**Topics**
+ [AppendFile （Linux、Windows、macOS）](#action-modules-appendfile)
+ [CopyFile （Linux、Windows、macOS）](#action-modules-copyfile)
+ [CopyFolder （Linux、Windows、macOS）](#action-modules-copyfolder)
+ [CreateFile （Linux、Windows、macOS）](#action-modules-createfile)
+ [CreateFolder （Linux、Windows、macOS）](#action-modules-createfolder)
+ [CreateSymlink （Linux、Windows、macOS）](#action-modules-createsymlink)
+ [DeleteFile （Linux、Windows、macOS）](#action-modules-deletefile)
+ [DeleteFolder （Linux、Windows、macOS）](#action-modules-deletefolder)
+ [ListFiles （Linux、Windows、macOS）](#action-modules-listfiles)
+ [MoveFile （Linux、Windows、macOS）](#action-modules-movefile)
+ [MoveFolder （Linux、Windows、macOS）](#action-modules-movefolder)
+ [ReadFile （Linux、Windows、macOS）](#action-modules-readfile)
+ [SetFileEncoding （Linux、Windows、macOS）](#action-modules-setfileencoding)
+ [SetFileOwner （Linux、Windows、macOS）](#action-modules-setfileowner)
+ [SetFolderOwner （Linux、Windows、macOS）](#action-modules-setfolderowner)
+ [SetFilePermissions （Linux、Windows、macOS）](#action-modules-setfilepermissions)
+ [SetFolderPermissions （Linux、Windows、macOS）](#action-modules-setfolderpermissions)
### AppendFile （Linux、Windows、macOS）
**AppendFile**操作模块将指定内容添加到文件中先前存在的内容中。
如果文件编码值与默认编码 (`utf-8`) 值不同，可以使用 `encoding` 选项指定文件编码值。默认情况下，`utf-16` 和 `utf-32` 使用小端字节序编码。
发生以下情况时，操作模块会返回错误：
+ 指定的文件在运行时不存在。
+ 您没有修改文件内容的写入权限。
+ 该模块在文件操作期间遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| content | 要附加到文件的内容。 | 字符串 | 否 | 空字符串 | 不适用 | 是 |
| encoding | 编码标准。 | 字符串 | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BE 和 utf-32-BE。编码选项的值不区分大小写。 | 是 |
**输入示例：附加文件而不编码（Linux）**
```
- name: AppendingFileWithOutEncodingLinux
action: AppendFile
inputs:
- path: ./Sample.txt
content: "The string to be appended to the file"
```
**输入示例：附加文件而不编码（Windows）**
```
- name: AppendingFileWithOutEncodingWindows
action: AppendFile
inputs:
- path: C:\MyFolder\MyFile.txt
content: "The string to be appended to the file"
```
**输入示例：附加文件并编码（Linux）**
```
- name: AppendingFileWithEncodingLinux
action: AppendFile
inputs:
- path: /FolderName/SampleFile.txt
content: "The string to be appended to the file"
encoding: UTF-32
```
**输入示例：附加文件并编码（Windows）**
```
- name: AppendingFileWithEncodingWindows
action: AppendFile
inputs:
- path: C:\MyFolderName\SampleFile.txt
content: "The string to be appended to the file"
encoding: UTF-32
```
**输入示例：以空字符串附加文件（Linux）**
```
- name: AppendingEmptyStringLinux
action: AppendFile
inputs:
- path: /FolderName/SampleFile.txt
```
**输入示例：以空字符串附加文件（Windows）**
```
- name: AppendingEmptyStringWindows
action: AppendFile
inputs:
- path: C:\MyFolderName\SampleFile.txt
```
**Output**
无。
### CopyFile （Linux、Windows、macOS）
**CopyFile**操作模块将文件从指定源复制到指定目标。默认情况下，如果目标文件夹在运行时不存在，该模块将会以递归方式创建该文件夹。
如果指定文件夹中已存在具有指定名称的文件，则默认情况下，操作模块将覆盖现有文件。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。当覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。此选项的工作原理与 Linux 中的 `cp` 命令相同，默认情况下会覆盖。
源文件名可以包含通配符 (`*`)。只有在最后一个文件路径分隔符（`/` 或 `\`）之后才可使用通配符。如果源文件名中包含通配符，则所有与通配符匹配的文件都将复制到目标文件夹。如果要使用通配符移动多个文件，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾，这表示目标输入是一个文件夹。
如果目标文件名与源文件名不同，则可以使用 `destination` 选项指定目标文件名。如果未指定目标文件名，则使用源文件的名称来创建目标文件。最后一个文件路径分隔符（`/` 或 `\`）之后的任何文本都将视为文件名。如果要使用与源文件相同的文件名，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾。
发生以下情况时，操作模块会返回错误：
+ 您无权在指定文件夹中创建文件。
+ 源文件在运行时不存在。
+ 已存在具有指定文件名的文件夹，且 `overwrite` 选项设置为 `false`。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| source | 源文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| destination | 目标文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| overwrite | 如果设置为错误，当指定位置已经存在具有指定名称的文件时，目标文件将不会被替换。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：复制文件（Linux）**
```
- name: CopyingAFileLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
```
**输入示例：复制文件（Windows）**
```
- name: CopyingAFileWindows
action: CopyFile
inputs:
- source: C:\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
```
**输入示例：使用源文件名复制文件（Linux）**
```
- name: CopyingFileWithSourceFileNameLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/
```
**输入示例：使用源文件名复制文件（Windows）**
```
- name: CopyingFileWithSourceFileNameWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\
```
**输入示例：使用通配符复制文件（Linux）**
```
- name: CopyingFilesWithWildCardLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**输入示例：使用通配符复制文件（Windows）**
```
- name: CopyingFilesWithWildCardWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**输入示例：复制文件而不覆盖（Linux）**
```
- name: CopyingFilesWithoutOverwriteLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
overwrite: false
```
**输入示例：复制文件而不覆盖（Windows）**
```
- name: CopyingFilesWithoutOverwriteWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
overwrite: false
```
**Output**
无。
### CopyFolder （Linux、Windows、macOS）
**CopyFolder**操作模块将文件夹从指定源复制到指定目标。`source` 选项的输入为要复制的文件夹，`destination` 选项的输入为源文件夹内容被复制的文件夹。默认情况下，如果目标文件夹在运行时不存在，该模块将会以递归方式创建该文件夹。
如果指定文件夹中已经存在具有指定名称的文件夹，则默认情况下，操作模块会覆盖现有文件夹。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。如果将覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。
源文件夹名称可以包含通配符 (`*`)。只有在最后一个文件路径分隔符（`/` 或 `\`）之后才可使用通配符。如果源文件夹名称中包含通配符，则所有与通配符匹配的文件夹都将复制到目标文件夹。如果要使用通配符复制多个文件夹，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾，这表示目标输入是一个文件夹。
如果目标文件夹名称与源文件夹名称不同，则可以使用 `destination` 选项指定目标文件夹名称。如果未指定目标文件夹名称，则使用源文件夹的名称来创建目标文件夹。最后一个文件路径分隔符（`/` 或 `\`）之后的任何文本都将视为文件夹名称。如果要使用与源文件夹相同的文件夹名称，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾。
发生以下情况时，操作模块会返回错误：
+ 您无权在指定文件夹中创建文件夹。
+ 源文件夹在运行时不存在。
+ 已存在具有指定文件夹名称的文件夹，且 `overwrite` 选项设置为 `false`。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| source | 源文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| destination | 目标文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| overwrite | 如果设置为错误，当指定位置中已经存在具有指定名称的文件夹时，目标文件夹将不会被替换。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：复制文件夹（Linux）**
```
- name: CopyingAFolderLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/destinationFolder
```
**输入示例：复制文件夹（Windows）**
```
- name: CopyingAFolderWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\destinationFolder
```
**输入示例：使用源文件夹名称复制文件夹（Linux）**
```
- name: CopyingFolderSourceFolderNameLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/
```
**输入示例：使用源文件夹名称复制文件夹（Windows）**
```
- name: CopyingFolderSourceFolderNameWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\
```
**输入示例：使用通配符复制文件夹（Linux）**
```
- name: CopyingFoldersWithWildCardLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**输入示例：使用通配符复制文件夹（Windows）**
```
- name: CopyingFoldersWithWildCardWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**输入示例：在不覆盖的情况下复制文件夹（Linux）**
```
- name: CopyingFoldersWithoutOverwriteLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/destinationFolder
overwrite: false
```
**输入示例：在不覆盖的情况下复制文件夹（Windows）**
```
- name: CopyingFoldersWithoutOverwrite
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SourceFolder
destination: C:\MyFolder\destinationFolder
overwrite: false
```
**Output**
无。
### CreateFile （Linux、Windows、macOS）
**CreateFile**操作模块在指定位置创建文件。默认情况下，如有需要，该模块还会以递归方式创建父文件夹。
如果指定文件夹中已存在该文件，则默认情况下，操作模块会截断或覆盖现有文件。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。当覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。
如果文件编码值与默认编码 (`utf-8`) 值不同，可以使用 `encoding` 选项指定文件编码值。默认情况下，`utf-16` 和 `utf-32` 使用小端字节序编码。
`owner`、`group`、和 `permissions` 是可选输入。`permissions` 的输入必须是字符串值。如果未提供默认值，将使用默认值创建文件。Windows 平台不支持这些选项。如果在 Windows 平台上使用选项 `owner`、`group` 和 `permissions`，则此操作模块将验证并返回错误。
此操作模块可以创建一个文件，其权限由操作系统的默认 `umask` 值定义。如果想覆盖默认值，则必须设置 `umask` 值。
发生以下情况时，操作模块会返回错误：
+ 您无权在指定的父文件夹中创建文件或文件夹。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| content | 文件的文本内容。 | 字符串 | 否 | 不适用 | 不适用 | 是 |
| encoding | 编码标准。 | 字符串 | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BE 和 utf-32-BE。编码选项的值不区分大小写。 | 是 |
| owner | 用户名或 ID。 | 字符串 | 否 | 不适用 | 不适用 | Windows 中不支持。 |
| group | 组名称或 ID。 | 字符串 | 否 | 当前用户。 | 不适用 | Windows 中不支持。 |
| permissions | 文件权限。 | 字符串 | 否 | 0666 | 不适用 | Windows 中不支持。 |
| overwrite | 如果指定文件的名称已经存在，则默认情况下，将此值设置为 false 可防止文件被截断或覆盖。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：创建文件而不覆盖（Linux）**
```
- name: CreatingFileWithoutOverwriteLinux
action: CreateFile
inputs:
- path: /home/UserName/Sample.txt
content: The text content of the sample file.
overwrite: false
```
**输入示例：创建文件而不覆盖（Windows）**
```
- name: CreatingFileWithoutOverwriteWindows
action: CreateFile
inputs:
- path: C:\Temp\Sample.txt
content: The text content of the sample file.
overwrite: false
```
**输入示例：创建带文件属性的文件**
```
- name: CreatingFileWithFileProperties
action: CreateFile
inputs:
- path: SampleFolder/Sample.txt
content: The text content of the sample file.
encoding: UTF-16
owner: Ubuntu
group: UbuntuGroup
permissions: 0777
- path: SampleFolder/SampleFile.txt
permissions: 755
- path: SampleFolder/TextFile.txt
encoding: UTF-16
owner: root
group: rootUserGroup
```
**输入示例：创建不带文件属性的文件**
```
- name: CreatingFileWithoutFileProperties
action: CreateFile
inputs:
- path: ./Sample.txt
- path: Sample1.txt
```
**输入示例：创建一个空文件以跳过 Linux 清理脚本中的某一部分**
```
- name: CreateSkipCleanupfile
action: CreateFile
inputs:
- path:
```
有关更多信息，请参阅 [覆盖 Linux 清理脚本](security-best-practices.md#override-linux-cleanup-script)
**Output**
无。
### CreateFolder （Linux、Windows、macOS）
**CreateFolder**操作模块在指定位置创建一个文件夹。默认情况下，如有需要，该模块还会以递归方式创建父文件夹。
如果指定文件夹中已存在该文件夹，则默认情况下，操作模块会截断或覆盖现有文件夹。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。如果将覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。
`owner`、`group`、和 `permissions` 是可选输入。`permissions` 的输入必须是字符串值。Windows 平台不支持这些选项。如果在 Windows 平台上使用选项 `owner`、`group` 和 `permissions`，则此操作模块将验证并返回错误。
此操作模块可以创建一个文件夹，其权限由操作系统的默认 `umask` 值定义。如果想覆盖默认值，则必须设置 `umask` 值。
发生以下情况时，操作模块会返回错误：
+ 您无权在指定位置创建文件夹。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| owner | 用户名或 ID。 | 字符串 | 否 | 当前用户。 | 不适用 | Windows 中不支持。 |
| group | 组名称或 ID。 | 字符串 | 否 | 当前用户的组。 | 不适用 | Windows 中不支持。 |
| permissions | 文件夹权限。 | 字符串 | 否 | 0777 | 不适用 | Windows 中不支持。 |
| overwrite | 如果指定文件的名称已经存在，则默认情况下，将此值设置为 false 可防止文件被截断或覆盖。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：创建文件夹（Linux）**
```
- name: CreatingFolderLinux
action: CreateFolder
inputs:
- path: /Sample/MyFolder/
```
**输入示例：创建文件夹（Windows）**
```
- name: CreatingFolderWindows
action: CreateFolder
inputs:
- path: C:\MyFolder
```
**输入示例：创建指定文件夹属性的文件夹**
```
- name: CreatingFolderWithFolderProperties
action: CreateFolder
inputs:
- path: /Sample/MyFolder/Sample/
owner: SampleOwnerName
group: SampleGroupName
permissions: 0777
- path: /Sample/MyFolder/SampleFoler/
permissions: 777
```
**输入示例：创建一个覆盖现有文件夹的文件夹（如有）。**
```
- name: CreatingFolderWithOverwrite
action: CreateFolder
inputs:
- path: /Sample/MyFolder/Sample/
overwrite: true
```
**Output**
无。
### CreateSymlink （Linux、Windows、macOS）
**CreateSymlink**操作模块创建符号链接或包含对另一个文件的引用的文件。Windows 平台不支持此模块。
`path` 和 `target` 选项的输入可以是绝对路径，也可以是相对路径。如果 `path` 选项的输入是相对路径，则在创建链接时它将替换为绝对路径。
默认情况下，当指定文件夹中已存在具有指定名称的链接时，操作模块会返回错误。您可以将 `force` 选项设置为 `true`，覆盖这一默认行为。当 `force` 选项设置为 `true` 时，模块将覆盖现有链接。
如果父文件夹不存在，则默认情况下，操作模块会以递归方式创建该文件夹。
发生以下情况时，操作模块会返回错误：
+ 目标文件在运行时不存在。
+ 已存在具有指定名称的非符号链接文件。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| target | 符号链接指向的目标文件路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| force | 当名称相同的链接存在时，将强制创建链接。 | 布尔值 | 否 | false | 不适用 | Windows 中不支持。 |
**输入示例：创建强制创建链接的符号链接**
```
- name: CreatingSymbolicLinkWithForce
action: CreateSymlink
inputs:
- path: /Folder2/Symboliclink.txt
target: /Folder/Sample.txt
force: true
```
**输入示例：创建不强制创建链接的符号链接**
```
- name: CreatingSymbolicLinkWithOutForce
action: CreateSymlink
inputs:
- path: Symboliclink.txt
target: /Folder/Sample.txt
```
**Output**
无。
### DeleteFile （Linux、Windows、macOS）
**DeleteFile**操作模块删除指定位置的一个或多个文件。
`path` 的输入应该是有效的文件路径或文件名中带有通配符 (`*`) 的文件路径。如果在文件名中已指定通配符，则同一文件夹中与通配符匹配的所有文件都将被删除。
发生以下情况时，操作模块会返回错误：
+ 您无权执行删除的操作。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
**输入示例：删除单个文件（Linux）**
```
- name: DeletingSingleFileLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/Sample.txt
```
**输入示例：删除单个文件（Windows）**
```
- name: DeletingSingleFileWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\Sample.txt
```
**输入示例：删除以“日志”结尾的文件（Linux）**
```
- name: DeletingFileEndingWithLogLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/*log
```
**输入示例：删除以“日志”结尾的文件（Windows）**
```
- name: DeletingFileEndingWithLogWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\*log
```
**输入示例：删除指定文件夹中的所有文件（Linux）**
```
- name: DeletingAllFilesInAFolderLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/*
```
**输入示例：删除指定文件夹中的所有文件（Windows）**
```
- name: DeletingAllFilesInAFolderWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\*
```
**Output**
无。
### DeleteFolder （Linux、Windows、macOS）
**DeleteFolder**操作模块删除文件夹。
如果该文件夹不为空，则必须将 `force` 选项设置为 `true` 才能删除该文件夹及其内容。如果您未将 `force` 选项设置为 `true`，并且您要删除的文件夹不为空，则操作模块会返回错误。`force` 选项的默认值为 `false`。
发生以下情况时，操作模块会返回错误：
+ 您无权执行删除的操作。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| force | 无论文件夹是否为空，都将删除该文件夹。 | 布尔值 | 否 | false | 不适用 | 是 |
**输入示例：使用 `force` 选项删除非空文件夹（Linux）**
```
- name: DeletingFolderWithForceOptionLinux
action: DeleteFolder
inputs:
- path: /Sample/MyFolder/Sample/
force: true
```
**输入示例：使用 `force` 选项删除非空文件夹（Windows）**
```
- name: DeletingFolderWithForceOptionWindows
action: DeleteFolder
inputs:
- path: C:\Sample\MyFolder\Sample\
force: true
```
**输入示例：删除文件夹（Linux）**
```
- name: DeletingFolderWithOutForceLinux
action: DeleteFolder
inputs:
- path: /Sample/MyFolder/Sample/
```
**输入示例：删除文件夹（Windows）**
```
- name: DeletingFolderWithOutForce
action: DeleteFolder
inputs:
- path: C:\Sample\MyFolder\Sample\
```
**Output**
无。
### ListFiles （Linux、Windows、macOS）
**ListFiles**操作模块列出了指定文件夹中的文件。当递归选项设置为 `true` 时，将列出子文件夹中的文件。默认情况下，此模块不列出子文件夹中的文件。
要列出名称与指定模式匹配的所有文件，请使用 `fileNamePattern` 选项提供该模式。`fileNamePattern` 选项接受通配符 (`*`) 值。提供 `fileNamePattern` 时，将返回与指定文件名格式匹配的所有文件。
发生以下情况时，操作模块会返回错误：
+ 指定的文件夹在运行时不存在。
+ 您无权在指定的父文件夹中创建文件或文件夹。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| fileNamePattern | 要匹配以列出名称与该模式匹配的所有文件的模式。 | 字符串 | 否 | 不适用 | 不适用 | 是 |
| recursive | 递归列出文件夹中的文件。 | 布尔值 | 否 | false | 不适用 | 是 |
**输入示例：列出指定文件夹中的文件（Linux）**
```
- name: ListingFilesInSampleFolderLinux
action: ListFiles
inputs:
- path: /Sample/MyFolder/Sample
```
**输入示例：列出指定文件夹中的文件（Windows）**
```
- name: ListingFilesInSampleFolderWindows
action: ListFiles
inputs:
- path: C:\Sample\MyFolder\Sample
```
**输入示例：列出以“日志”结尾的文件（Linux）**
```
- name: ListingFilesWithEndingWithLogLinux
action: ListFiles
inputs:
- path: /Sample/MyFolder/
fileNamePattern: *log
```
**输入示例：列出以“日志”结尾的文件（Windows）**
```
- name: ListingFilesWithEndingWithLogWindows
action: ListFiles
inputs:
- path: C:\Sample\MyFolder\
fileNamePattern: *log
```
**输入示例：递归列出文件**
```
- name: ListingFilesRecursively
action: ListFiles
inputs:
- path: /Sample/MyFolder/
recursive: true
```
**Output**
| 键名称 | 说明 | Type |
| --- | --- | --- |
| files | 文件列表。 | 字符串 |
**输出示例**
```
{
"files": "/sample1.txt,/sample2.txt,/sample3.txt"
}
```
### MoveFile （Linux、Windows、macOS）
**MoveFile**操作模块将文件从指定源移动到指定目标。
如果指定文件夹中已存在该文件，则默认情况下，操作模块会覆盖现有文件。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。当覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。此选项的工作原理与 Linux 中的 `mv` 命令相同，默认情况下会覆盖。
源文件名可以包含通配符 (`*`)。只有在最后一个文件路径分隔符（`/` 或 `\`）之后才可使用通配符。如果源文件名中包含通配符，则所有与通配符匹配的文件都将复制到目标文件夹。如果要使用通配符移动多个文件，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾，这表示目标输入是一个文件夹。
如果目标文件名与源文件名不同，则可以使用 `destination` 选项指定目标文件名。如果未指定目标文件名，则使用源文件的名称来创建目标文件。最后一个文件路径分隔符（`/` 或 `\`）之后的任何文本都将视为文件名。如果要使用与源文件相同的文件名，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾。
发生以下情况时，操作模块会返回错误：
+ 您无权在指定文件夹中创建文件。
+ 源文件在运行时不存在。
+ 已存在具有指定文件名的文件夹，且 `overwrite` 选项设置为 `false`。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| source | 源文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| destination | 目标文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| overwrite | 如果设置为错误，当指定位置已经存在具有指定名称的文件时，目标文件将不会被替换。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：移动文件（Linux）**
```
- name: MovingAFileLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
```
**输入示例：移动文件（Windows）**
```
- name: MovingAFileWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
```
**输入示例：使用源文件名移动文件（Linux）**
```
- name: MovingFileWithSourceFileNameLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/
```
**输入示例：使用源文件名移动文件（Windows）**
```
- name: MovingFileWithSourceFileNameWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder
```
**输入示例：使用通配符移动文件（Linux）**
```
- name: MovingFilesWithWildCardLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**输入示例：使用通配符移动文件（Windows）**
```
- name: MovingFilesWithWildCardWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder
```
**输入示例：移动文件而不覆盖（Linux）**
```
- name: MovingFilesWithoutOverwriteLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
overwrite: false
```
**输入示例：移动文件而不覆盖（Windows）**
```
- name: MovingFilesWithoutOverwrite
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
overwrite: false
```
**Output**
无。
### MoveFolder （Linux、Windows、macOS）
**MoveFolder**操作模块将文件夹从指定源移动到指定目标。`source` 选项的输入是要移动的文件夹，而 `destination` 选项的输入是源文件夹内容被移动的文件夹。
如果目标父文件夹或 `destination` 选项的输入在运行时不存在，则默认情况下，模块会在指定的目标上递归创建文件夹。
如果目标文件夹中已存在与源文件夹相同的文件夹，则默认情况下，操作模块会覆盖现有文件夹。您可以将覆盖选项设置为 `false`，覆盖这一默认行为。如果将覆盖选项设置为 `false`，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。
源文件夹名称可以包含通配符 (`*`)。只有在最后一个文件路径分隔符（`/` 或 `\`）之后才可使用通配符。如果源文件夹名称中包含通配符，则所有与通配符匹配的文件夹都将复制到目标文件夹。如果要使用通配符移动多个文件夹，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾，这表示目标输入是一个文件夹。
如果目标文件夹名称与源文件夹名称不同，则可以使用 `destination` 选项指定目标文件夹名称。如果未指定目标文件夹名称，则使用源文件夹的名称来创建目标文件夹。最后一个文件路径分隔符（`/` 或 `\`）之后的任何文本都将视为文件夹名称。如果要使用与源文件夹相同的文件夹名称，则 `destination` 选项的输入必须以文件路径分隔符（`/` 或 `\`）结尾。
发生以下情况时，操作模块会返回错误：
+ 您无权在目标文件夹中创建文件夹。
+ 源文件夹在运行时不存在。
+ 已存在具有指定名称的文件夹，且 `overwrite` 选项设置为 `false`。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| source | 源文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| destination | 目标文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| overwrite | 如果设置为错误，当指定位置中已经存在具有指定名称的文件夹时，目标文件夹将不会被替换。 | 布尔值 | 否 | true | 不适用 | 是 |
**输入示例：移动文件夹（Linux）**
```
- name: MovingAFolderLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/destinationFolder
```
**输入示例：移动文件夹（Windows）**
```
- name: MovingAFolderWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SourceFolder
destination: C:\MyFolder\destinationFolder
```
**输入示例：使用源文件夹名称移动文件夹（Linux）**
```
- name: MovingFolderWithSourceFolderNameLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/
```
**输入示例：使用源文件夹名称移动文件夹（Windows）**
```
- name: MovingFolderWithSourceFolderNameWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\
```
**输入示例：使用通配符移动文件夹（Linux）**
```
- name: MovingFoldersWithWildCardLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**输入示例：使用通配符移动文件夹（Windows）**
```
- name: MovingFoldersWithWildCardWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**输入示例：在不覆盖的情况下移动文件夹（Linux）**
```
- name: MovingFoldersWithoutOverwriteLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/destinationFolder
overwrite: false
```
**输入示例：在不覆盖的情况下移动文件夹（Windows）**
```
- name: MovingFoldersWithoutOverwriteWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\destinationFolder
overwrite: false
```
**Output**
无。
### ReadFile （Linux、Windows、macOS）
**ReadFile**操作模块读取字符串类型的文本文件的内容。该模块可用于读取文件内容，以便通过链接在后续步骤中使用，或者用于读取数据到 `console.log` 文件。如果指定的路径是符号链接，则此模块将返回目标文件的内容。该模块仅支持文本文件。
如果文件编码值与默认编码 (`utf-8`) 值不同，可以使用 `encoding` 选项指定文件编码值。默认情况下，`utf-16` 和 `utf-32` 使用小端字节序编码。
默认情况下，此模块无法将文件内容打印到 `console.log` 文件中。您可以通过将 `printFileContent` 属性设置为 `true` 来覆盖此设置。
该模块只能返回文件的内容。该模块无法解析文件（例如 Excel 或 JSON 文件）。
发生以下情况时，操作模块会返回错误：
+ 该文件在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| encoding | 编码标准。 | 字符串 | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BE 和 utf-32-BE。编码选项的值不区分大小写。 | 是 |
| printFileContent | 将文件内容打印到 console.log 文件中。 | 布尔值 | 否 | false | 不适用 | 可以。 |
**输入示例：读取文件（Linux）**
```
- name: ReadingFileLinux
action: ReadFile
inputs:
- path: /home/UserName/SampleFile.txt
```
**输入示例：读取文件（Windows）**
```
- name: ReadingFileWindows
action: ReadFile
inputs:
- path: C:\Windows\WindowsUpdate.log
```
**输入示例：读取文件并指定编码标准**
```
- name: ReadingFileWithFileEncoding
action: ReadFile
inputs:
- path: /FolderName/SampleFile.txt
encoding: UTF-32
```
**输入示例：读取文件并将其打印到 `console.log` 文件**
```
- name: ReadingFileToConsole
action: ReadFile
inputs:
- path: /home/UserName/SampleFile.txt
printFileContent: true
```
**Output**
| 字段 | 描述 | Type |
| --- | --- | --- |
| content | 文件内容。 | 字符串 |
**输出示例**
```
{
"content" : "The file content"
}
```
### SetFileEncoding （Linux、Windows、macOS）
**SetFileEncoding**操作模块修改现有文件的编码属性。该模块可以将文件编码从 `utf-8` 转换为指定的编码标准。默认情况下，`utf-16` 和 `utf-32` 为小端字节序编码。
发生以下情况时，操作模块会返回错误：
+ 您无权执行指定修改。
+ 该文件在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | 是 |
| encoding | 编码标准。 | 字符串 | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BE 和 utf-32-BE。编码选项的值不区分大小写。 | 是 |
**输入示例：设置文件编码属性**
```
- name: SettingFileEncodingProperty
action: SetFileEncoding
inputs:
- path: /home/UserName/SampleFile.txt
encoding: UTF-16
```
**Output**
无。
### SetFileOwner （Linux、Windows、macOS）
**SetFileOwner**操作模块修改现有文件的`owner`和`group`所有者属性。如果指定文件是符号链接，则模块将修改源文件的 `owner` 属性。Windows 平台不支持此模块。
该模块接受用户名和组名作为输入。如果未提供组名，则该模块会将文件的组所有者分配给该用户所属的组。
发生以下情况时，操作模块会返回错误：
+ 您无权执行指定修改。
+ 指定的用户名或组名在运行时不存在。
+ 该文件在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| owner | 用户名。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| group | 用户组的名称。 | 字符串 | 否 | 用户属于的组的名称。 | 不适用 | Windows 中不支持。 |
**输入示例：设置文件所有者属性而不指定用户组名称**
```
- name: SettingFileOwnerPropertyNoGroup
action: SetFileOwner
inputs:
- path: /home/UserName/SampleText.txt
owner: LinuxUser
```
**输入示例：通过指定所有者和用户组来设置文件所有者属性**
```
- name: SettingFileOwnerProperty
action: SetFileOwner
inputs:
- path: /home/UserName/SampleText.txt
owner: LinuxUser
group: LinuxUserGroup
```
**Output**
无。
### SetFolderOwner （Linux、Windows、macOS）
**SetFolderOwner**操作模块以递归方式修改现有文件夹的`owner`和`group`所有者属性。默认情况下，该模块可以修改文件夹中所有内容的所有权。您可以将 `recursive` 选项设置为 `false` 以覆盖此行为。Windows 平台不支持此模块。
该模块接受用户名和组名作为输入。如果未提供组名，则该模块会将文件的组所有者分配给该用户所属的组。
发生以下情况时，操作模块会返回错误：
+ 您无权执行指定修改。
+ 指定的用户名或组名在运行时不存在。
+ 该文件夹在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| owner | 用户名。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| group | 用户组的名称。 | 字符串 | 否 | 用户属于的组的名称。 | 不适用 | Windows 中不支持。 |
| recursive | 如果设置为 false，将覆盖修改文件夹所有内容所有权的默认行为。 | 布尔值 | 否 | true | 不适用 | Windows 中不支持。 |
**输入示例：设置文件夹所有者属性而不指定用户组名称**
```
- name: SettingFolderPropertyWithOutGroup
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
```
**输入示例：设置文件夹所有者属性而不覆盖文件夹中所有内容的所有权**
```
- name: SettingFolderPropertyWithOutRecursively
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
recursive: false
```
**输入示例：通过指定用户组名称来设置文件所有权属性**
```
- name: SettingFolderPropertyWithGroup
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
group: LinuxUserGroup
```
**Output**
无。
### SetFilePermissions （Linux、Windows、macOS）
**SetFilePermissions**操作模块修改现有文件的。`permissions`Windows 平台不支持此模块。
`permissions` 的输入必须是字符串值。
此操作模块将创建一个文件，其权限由操作系统默认的 umask 值定义。如果想覆盖默认值，则必须设置 `umask` 值。
发生以下情况时，操作模块会返回错误：
+ 您无权执行指定修改。
+ 该文件在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| permissions | 文件权限。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
**输入示例：修改文件权限**
```
- name: ModifyingFilePermissions
action: SetFilePermissions
inputs:
- path: /home/UserName/SampleFile.txt
permissions: 766
```
**Output**
无。
### SetFolderPermissions （Linux、Windows、macOS）
**SetFolderPermissions**操作模块以递归方式修改现有文件夹及其所有子文件和子文件夹。`permissions`默认情况下，此模块可以修改指定文件夹中所有内容的权限。您可以将 `recursive` 选项设置为 `false` 以覆盖此行为。Windows 平台不支持此模块。
`permissions` 的输入必须是字符串值。
此操作模块可以根据操作系统的默认 umask 值修改权限。如果想覆盖默认值，则必须设置 `umask` 值。
发生以下情况时，操作模块会返回错误：
+ 您无权执行指定修改。
+ 该文件夹在运行时不存在。
+ 操作模块在执行操作时遇到错误。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 | 支持全平台 |
| --- | --- | --- | --- | --- | --- | --- |
| path | 文件夹路径。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| permissions | 文件夹权限。 | 字符串 | 是 | 不适用 | 不适用 | Windows 中不支持。 |
| recursive | 如果设置为 false，将覆盖修改文件夹所有内容权限的默认行为。 | 布尔值 | 否 | true | 不适用 | Windows 中不支持。 |
**输入示例：设置文件夹权限**
```
- name: SettingFolderPermissions
action: SetFolderPermissions
inputs:
- path: SampleFolder/
permissions: 0777
```
**输入示例：设置文件夹权限而不修改文件夹所有内容的权限**
```
- name: SettingFolderPermissionsNoRecursive
action: SetFolderPermissions
inputs:
- path: /home/UserName/SampleFolder/
permissions: 777
recursive: false
```
**Output**
无。
## 软件安装操作
下一部分介绍了安装或卸载软件的操作模块。
**IAM 要求**
如果您的安装下载路径是 S3 URI，则与您的实例配置文件关联的 IAM 角色必须具有运行 `S3Download` 操作模块的权限。要授予所需权限，请将 `S3:GetObject` IAM 策略附加到与实例配置文件关联的 IAM 角色，并指定存储桶的路径。例如，`arn:aws:s3:::BucketName/*`）。
**复杂 MSI 输入**
如果您的输入字符串包含双引号字符 (`"`)，则必须使用以下方法之一来确保其得到正确解释：
+ 您可以在字符串的外部使用单引号（'）来包含它，并在字符串内部使用双引号（"），如下面的示例所示。
```
properties:
COMPANYNAME: '"Acme ""Widgets"" and ""Gizmos."""'
```
在这种情况下，如果您需要在字符串中使用撇号，则必须对其进行转义。这意味着需要在撇号前使用另一个单引号（'）。
+ 你可以在字符串的外面使用双引号（"）来包含它。您可以使用反斜杠字符 (`\`) 对字符串中的任何双引号进行转义，如以下示例所示。
```
properties:
COMPANYNAME: "\"Acme \"\"Widgets\"\" and \"\"Gizmos.\"\"\""
```
这两种方法都将值 `COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""` 传递给 **msiexec** 命令。
**Topics**
+ [InstallMSI (Windows)](#action-modules-install-msi)
+ [UninstallMSI (Windows)](#action-modules-uninstall-msi)
### InstallMSI (Windows)
`InstallMSI` 操作模块使用 MSI 文件安装 Windows 应用程序。您可以使用本地路径、S3 对象 URI 或 Web URL 来指定 MSI 文件。重新启动选项可配置系统的重新启动行为。
AWSTOE 根据操作模块的输入参数生成**msiexec**命令。`path`（MSI 文件位置）和 `logFile`（日志文件位置）输入参数的值必须用引号（"）括起来。
以下 MSI 退出代码视为成功：
+ 0（成功）
+ 1614（ERROR\$1PRODUCT\$1UNINSTALLED）
+ 1641（已启动重启）
+ 3010（需要重启）
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 |
| --- | --- | --- | --- | --- | --- |
| path | 使用以下之一指定 MSI 文件位置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) 允许使用链接表达式。 | 字符串 | 是 | 不适用 | 不适用 |
| reboot | 配置成功运行操作模块后的系统重启行为。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 字符串 | 否 | Allow | Allow, Force, Skip |
| logOptions | 指定用于 MSI 安装日志的选项。指定的标志与 `/L` 命令行参数一起传递给 MSI 安装程序，以启用日志记录。如果未指定任何标志，则 AWSTOE 使用默认值。 有关 MSI 日志选项的更多信息，请参阅 Microsoft *Windows Installer* 产品文档中的 [命令行选项](https://learn.microsoft.com/en-us/windows/win32/msi/command-line-options)。 | 字符串 | 否 | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 |
| logFile | 日志文件位置的绝对路径或相对路径。如果该日志文件路径不存在，请创建它。如果未提供日志文件路径，则 AWSTOE 不存储 MSI 安装日志。 | 字符串 | 否 | 不适用 | 不适用 |
| properties | MSI 日志属性键值对，例如：`TARGETDIR: "C:\target\location"` 注意：不允许修改以下属性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | 否 | 不适用 | 不适用 |
| ignoreAuthenticodeSignatureErrors | 忽略路径中指定的安装程序的 authenticode 签名验证错误的标志。**Get-AuthenticodeSignature** 命令用于验证安装程序。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 布尔值 | 否 | false | true, false |
| allowUnsignedInstaller | 允许运行路径中指定的未签名安装程序的标志。**Get-AuthenticodeSignature** 命令用于验证安装程序。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 布尔值 | 否 | false | true, false |
**示例**
以下示例显示了组件文档输入部分的变体，具体取决于您的安装路径。
**输入示例：本地文档路径安装**
```
- name: local-path-install
steps:
- name: LocalPathInstaller
action: InstallMSI
inputs:
path: C:\sample.msi
logFile: C:\msilogs\local-path-install.log
logOptions: '*VX'
reboot: Allow
properties:
COMPANYNAME: '"Amazon Web Services"'
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: true
```
**输入示例：Amazon S3 路径安装**
```
- name: s3-path-install
steps:
- name: S3PathInstaller
action: InstallMSI
inputs:
path: s3:///sample.msi
logFile: s3-path-install.log
reboot: Force
ignoreAuthenticodeSignatureErrors: false
allowUnsignedInstaller: true
```
**输入示例：Web 路径安装**
```
- name: web-path-install
steps:
- name: WebPathInstaller
action: InstallMSI
inputs:
path: https:///sample.msi
logFile: web-path-install.log
reboot: Skip
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: false
```
**Output**
以下是 `InstallMSI` 操作模块的输出示例。
```
{
"logFile": "web-path-install.log",
"msiExitCode": 0,
"stdout": ""
}
```
### UninstallMSI (Windows)
`UninstallMSI` 操作模块允许您使用 MSI 文件删除 Windows 应用程序。您可以使用本地文件路径、S3 对象 URI 或 Web URL 指定 MSI 文件位置。重新启动选项可配置系统的重新启动行为。
AWSTOE 根据操作模块的输入参数生成**msiexec**命令。生成 **msiexec** 命令时，MSI 文件位置 (`path`) 和日志文件位置 (`logFile`) 将明确用双引号（"）括起来。
以下 MSI 退出代码视为成功：
+ 0（成功）
+ 1605（ERROR\$1UNKNOWN\$1PRODUCT）
+ 1614（ERROR\$1PRODUCT\$1UNINSTALLED）
+ 1641（已启动重启）
+ 3010（需要重启）
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 值 | 可接受值 |
| --- | --- | --- | --- | --- | --- |
| path | 使用以下之一指定 MSI 文件位置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) 允许使用链接表达式。 | 字符串 | 是 | 不适用 | 不适用 |
| reboot | 配置成功运行操作模块后的系统重启行为。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 字符串 | 否 | Allow | Allow, Force, Skip |
| logOptions | 指定用于 MSI 安装日志的选项。指定的标志与 `/L` 命令行参数一起传递给 MSI 安装程序，以启用日志记录。如果未指定任何标志，则 AWSTOE 使用默认值。 有关 MSI 日志选项的更多信息，请参阅 Microsoft *Windows Installer* 产品文档中的 [命令行选项](https://docs.microsoft.com/en-us/windows/win32/msi/command-line-options)。 | 字符串 | 否 | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 |
| logFile | 日志文件位置的绝对路径或相对路径。如果该日志文件路径不存在，请创建它。如果未提供日志文件路径，则 AWSTOE 不存储 MSI 安装日志。 | 字符串 | 否 | 不适用 | 不适用 |
| properties | MSI 日志属性键值对，例如：`TARGETDIR: "C:\target\location"` 注意：不允许修改以下属性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | 否 | 不适用 | 不适用 |
| ignoreAuthenticodeSignatureErrors | 忽略路径中指定的安装程序的 authenticode 签名验证错误的标志。**Get-AuthenticodeSignature** 命令用于验证安装程序。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 布尔值 | 否 | false | true, false |
| allowUnsignedInstaller | 允许运行路径中指定的未签名安装程序的标志。**Get-AuthenticodeSignature** 命令用于验证安装程序。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) | 布尔值 | 否 | false | true, false |
**示例**
以下示例显示了组件文档输入部分的变体，具体取决于您的安装路径。
**输入示例：移除本地文档路径安装**
```
- name: local-path-uninstall
steps:
- name: LocalPathUninstaller
action: UninstallMSI
inputs:
path: C:\sample.msi
logFile: C:\msilogs\local-path-uninstall.log
logOptions: '*VX'
reboot: Allow
properties:
COMPANYNAME: '"Amazon Web Services"'
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: true
```
**输入示例：移除 Amazon S3 路径安装**
```
- name: s3-path-uninstall
steps:
- name: S3PathUninstaller
action: UninstallMSI
inputs:
path: s3:///sample.msi
logFile: s3-path-uninstall.log
reboot: Force
ignoreAuthenticodeSignatureErrors: false
allowUnsignedInstaller: true
```
**输入示例：移除 Web 路径安装**
```
- name: web-path-uninstall
steps:
- name: WebPathUninstaller
action: UninstallMSI
inputs:
path: https:///sample.msi
logFile: web-path-uninstall.log
reboot: Skip
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: false
```
**Output**
以下是 `UninstallMSI` 操作模块的输出示例。
```
{
"logFile": "web-path-uninstall.log",
"msiExitCode": 0,
"stdout": ""
}
```
## 系统操作模块
下一部分介绍了执行系统操作或更新系统设置的操作模块。
**Topics**
+ [Reboot（Linux、Windows）](#action-modules-reboot)
+ [SetRegistry （视窗）](#action-modules-setregistry)
+ [UpdateOS（Linux、Windows）](#action-modules-updateos)
### Reboot（Linux、Windows）
**重启** 操作模块重新引导实例。它具有一个可配置的选项以延迟启动重新引导。默认情况下，`delaySeconds` 设置为 `0`，表示没有延迟。由于在实例重启时步骤超时不适用，因此重启操作模块不支持步骤超时。
如果该应用程序是由 Systems Manager 代理调用的，则向 Systems Manager 代理返回退出代码（Windows 为 `3010`，Linux 为 `194`）。Systems Manager 代理处理系统重新引导，如[从脚本中重新引导托管实例](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。
如果该应用程序是在主机上作为单独进程调用的，它将保存当前执行状态，配置重新引导后自动运行触发器以重新执行该应用程序，然后重新引导系统。
**重新引导后自动运行触发器：**
+ **Windows**： AWSTOE 创建了一个 Windows 任务调度器条目，其触发器在 `SystemStartup` 自动运行
+ **Linux**： AWSTOE 在 crontab 中添加了一个在系统重启后自动运行的作业。
```
@reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml
```
在该应用程序启动时，将清除该触发器。
**重试**
默认情况下，最大重试次数设置为 Systems Manager `CommandRetryLimit`。如果重启次数超过重试限制，自动化将失败。您可以通过编辑 Systems Manager 代理配置文件（`Mds.CommandRetryLimit`）来更改限制。请参阅 Systems Manager 代理开源中的 [Runtime Configuration](https://github.com/aws/amazon-ssm-agent/blob/mainline/README.md#runtime-configuration)。
要使用 **Reboot** 操作模块，对于包含重新引导 `exitcode` 的步骤（例如，`3010`），您必须以 `sudo user` 形式运行应用程序二进制文件。
**Input**
| 键名称 | 说明 | Type | 必需 | 默认 |
| --- | --- | --- | --- | --- |
| delaySeconds | 在启动重新引导之前延迟特定的时间。 | 整数 | 否 | `0` |
**输入示例：重启步骤**
```
- name: RebootStep
action: Reboot
onFailure: Abort
maxAttempts: 2
inputs:
delaySeconds: 60
```
**输出**
无。
在 **重新引导** 模块完成后，Image Builder 继续执行构建中的下一步。
### SetRegistry （视窗）
**SetRegistry**操作模块接受输入列表，并允许您设置指定注册表项的值。如果注册表项不存在，则会在定义的路径中创建该注册表项。该功能仅适用于 Windows。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| path | 注册表项的路径。 | 字符串 | 是 |
| name | 注册表项的名称。 | 字符串 | 是 |
| value | 注册表项的值。 | String/Number/Array | 是 |
| type | 注册表项的值类型。 | 字符串 | 是 |
**支持的路径前缀**
+ `HKEY_CLASSES_ROOT / HKCR:`
+ `HKEY_USERS / HKU:`
+ `HKEY_LOCAL_MACHINE / HKLM:`
+ `HKEY_CURRENT_CONFIG / HKCC:`
+ `HKEY_CURRENT_USER / HKCU:`
**支持的类型**
+ `BINARY`
+ `DWORD`
+ `QWORD`
+ `SZ`
+ `EXPAND_SZ`
+ `MULTI_SZ`
**输入示例：设置注册表键值**
```
- name: SetRegistryKeyValues
action: SetRegistry
maxAttempts: 3
inputs:
- path: HKLM:\SOFTWARE\MySoftWare
name: MyName
value: FirstVersionSoftware
type: SZ
- path: HKEY_CURRENT_USER\Software\Test
name: Version
value: 1.1
type: DWORD
```
**输出**
无。
### UpdateOS（Linux、Windows）
**UpdateOS** 操作模块增加了对安装 Windows 和 Linux 更新的支持。默认情况下会安装所有可用更新。或者，您可以为待安装的操作模块配置一个或多个特定更新的列表。您也可以指定要从安装中排除的更新。
如果同时提供了“包括”和“排除”列表，则更新的结果列表只能包含在“包括”列表中列出并且在“排除”列表中未列出的那些更新。
**注意**
**UpdateOS** 不支持亚马逊 Linux 2023 () AL2023。我们建议您将基本 AMI 更新到每个发布版本附带的新版本。有关其他替代方案，请参阅 *Amazon Linux 2023 用户指南*中的[控制从主要版本和次要版本收到的更新](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html#controlling-release-updates)。
+ **Windows**。更新是从目标计算机上配置的更新源中安装的。
+ **Linux**。该应用程序检查 Linux 平台中支持的软件包管理器，并使用 `yum` 或 `apt-get` 软件包管理器。如果不支持这两个软件包管理器，则会返回错误。你应当拥有运行 **UpdateOS** 操作模块的 `sudo` 权限。如果您没有 `sudo` 权限，则会返回 `error.Input`。
**Input**
| 键名称 | 说明 | Type | 必需 |
| --- | --- | --- | --- |
| include | 对于 Windows，可以指定以下值： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) 对于 Linux，您可以指定一个或多个要包括在安装的更新列表中的软件包。 | 字符串列表 | 否 |
| exclude | 对于 Windows，可以指定以下值： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/toe-action-modules.html) 对于 Linux，您可以指定一个或多个要从安装的更新列表中排除的软件包。 | 字符串列表 | 否 |
**输入示例：添加对安装 Linux 更新的支持**
```
- name: UpdateMyLinux
action: UpdateOS
onFailure: Abort
maxAttempts: 3
inputs:
exclude:
- ec2-hibinit-agent
```
**输入示例：添加对安装 Windows 更新的支持**
```
- name: UpdateWindowsOperatingSystem
action: UpdateOS
onFailure: Abort
maxAttempts: 3
inputs:
include:
- KB1234567
- '*Security*'
```
**输出**
无。