AWSTOE 组件管理器支持的操作模块

映像构建服务（例如 EC2 Image Builder）使用 AWSTOE 操作模块来帮助配置用于构建和测试自定义机器映像的 EC2 实例。本节介绍常用 AWSTOE 操作模块的功能以及如何配置它们，包括示例。

AWSTOE 组件是用纯文本 YAML 文档创作的。有关文档语法的更多信息，请参阅 在中使用组件文档 AWSTOE 。

通用执行模块

下一部分详细介绍了执行一般执行命令和说明的操作模块。

ExecuteBash

ExecuteBash 操作模块允许您使用内联 shell 代码/命令运行 bash 脚本。该模块支持 Linux。

您在命令块中指定的所有命令和指令都将转换为文件（例如 input.sh ）并使用 bash Shell 执行。Shell 文件的执行结果是退出代码步骤。

如果脚本退出时退出代码为，则该 ExecuteBash 模块会处理系统重新启动。 194 在启动后，该应用程序执行以下操作之一：

如果是由 Systems Manager 代理执行的，该应用程序将向调用方返回退出代码。Systems Manager 代理处理系统重启并运行启动重启的步骤，如 从脚本重启托管实例 中所述。

该应用程序保存当前 executionstate ，配置重新启动触发器以重新执行该应用程序，然后重新启动系统。

在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。

输入示例：重启前后

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
              echo 'The reboot file does not exist. Creating it and triggering a restart.'
              touch "${REBOOT_INDICATOR}"
              exit 194

如果您执行重新引导，并返回退出代码 194 以作为操作模块的一部分，构建将在启动重新引导的同一操作模块步骤处继续执行。如果执行重新引导而没有退出代码，构建过程可能会失败。

输出示例：重启前（首次按照文档）

输出示例：重启后（第二次按照文档）

如果是由 Systems Manager 代理执行的，该应用程序将向调用方返回退出代码。Systems Manager 代理负责系统重启并运行启动重启的步骤，如 从脚本重启托管实例 中所述。

该应用程序保存当前 executionstate ，配置重新启动触发器以重新执行该应用程序，然后重新启动系统。

在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。

输入示例：安装 .NET

  - name: "InstallDotnet"
    action: ExecuteBinary
    inputs:
      path: C:\PathTo\dotnet_installer.exe
      arguments:
        - /qb
        - /norestart

ExecuteDocument

ExecuteDocument 操作模块增加了对嵌套组件文档的支持，从一个文档中运行多个组件文档。 AWSTOE 验证运行时在输入参数中传递的文档。

文档可以嵌套，最多可嵌套三层，不得超过此限制。三个嵌套级别转换为四个文档级别，因为顶层不是嵌套的。在这种情况下，最低级别的文档不得调用任何其他文档。

不允许循环执行组件文档。任何在循环结构之外调用自身文档，或者调用当前执行链中调用更高层的文档，都会引发循环，从而引发无限循环。当检测到循环执行时， AWSTOE 会停止执行并记录失败。

输入示例：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'
            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

AWSTOE 创建 detailedoutput.json 每次运行时都调用的输出文件。该文件包含运行时调用的每个组件文档的每个阶段和步骤的详细信息。对于 ExecuteDocument 操作模块，您可以在 outputs 字段中找到简短的运行时摘要，以及有关该模块在其中运行的阶段、步骤和文档的详细信息 detailedOutput 。

每个组件文档的输出摘要对象都包含以下详细信息以及示例值，如下所示：

以下示例显示了发生嵌套执行时 ExecuteDocument 操作模块的输出。在此示例中， main.yaml 组件文档成功运行了 Sample-1.yaml 组件文档。

ExecutePowerShell

ExecutePowerShell 操作模块允许您使用内联 shell 代码/命令运行 PowerShell 脚本。该模块支持 Windows 平台和 Windows PowerShell。

命令块中指定的所有命令/指令都将转换为脚本文件（例如 input.ps1 ），并使用 Windows 运行。PowerShellShell 文件的执行结果是退出代码。

如果 shell 命令退出时退出代码为，则该 ExecutePowerShell 模块将处理系统重新启动。 3010 在启动后，该应用程序执行以下操作之一：

如果由 Systems Manager 代理运行，则将退出代码交给调用者。Systems Manager 代理处理系统重启并运行启动重启的步骤，如 从脚本重启托管实例 中所述。

保存当前 executionstate ，配置重新启动触发器以重新运行该应用程序，然后重新引导系统。

在系统重新启动后，该应用程序执行触发重新启动的相同步骤。如果需要使用该功能，您必须编写幂等脚本以处理多次调用同一 Shell 命令的操作。

是。必须指定 commands 或 file ，但不能同时指定。

是。必须指定 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)

如果您执行重新引导，并返回退出代码 3010 以作为操作模块的一部分，构建将在启动重新引导的同一操作模块步骤处继续执行。如果执行重新引导而没有退出代码，构建过程可能会失败。

输出示例：重启前（首次按照文档）

输出示例：重启后（第二次按照文档）

S3Download

使用 S3Download 操作模块，您可以将 Amazon S3 对象或一组对象下载到您使用 destination 路径指定的本地文件或文件夹。如果指定位置已存在任何文件，且 overwrite 标志设置为正确，则 S3Download 会覆盖该文件。

source 位置可以指向 Amazon S3 中的特定对象，也可以使用带有星号通配符 ( * ) 的键前缀，以下载一组与键前缀路径匹配的对象。当您在 source 位置指定键前缀时， S3Download 操作模块会下载与该前缀匹配的所有内容（包括文件和文件夹）。确保键前缀以正斜杠结尾，后跟星号 ( /* )，以下载与该前缀匹配的所有内容。例如： s3://my-bucket/my-folder/* 。

如果在下载过程中对指定键前缀的 S3Download 操作失败，文件夹内容不会回滚到失败之前的状态。目标文件夹将保持失败时的状态。

支持的使用案例

S3Download 操作模块支持以下案例：

单个文件 ：针对存储桶/对象（例如 arn:aws:s3::: BucketName /* ）的 s3:GetObject 。

多个文件 ：针对存储桶/对象（例如 arn:aws:s3::: BucketName ）的 s3:ListBucket 以及针对存储桶/对象（例如 arn:aws:s3::: BucketName /* ）的 s3:GetObject 。

设置为正确时，如果指定本地路径的目标文件夹中已存在同名文件，下载文件将覆盖本地文件。如果设置为错误，可避免本地系统上的现有文件被覆盖，并且操作模块会因下载错误而失败。

例如， Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.

输入示例：将 Amazon S3 对象复制到本地文件

以下示例说明了如何将 Amazon S3 对象复制到本地文件。

  - name: DownloadMyFile
    action: S3Download
    inputs:
      - source: s3://mybucket/path/to/package.zip
        destination: C:\myfolder\package.zip
        expectedBucketOwner: 123456789022
        overwrite: false
      - source: s3://mybucket/path/to/package.zip
        destination: C:\myfolder\package.zip
        expectedBucketOwner: 123456789022
        overwrite: true
      - source: s3://mybucket/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://mybucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022
        overwrite: false
      - source: s3://mybucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022
        overwrite: true
      - source: s3://mybucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022

S3Upload

使用 S3Upload 操作模块可以将文件从源文件/文件夹上传到某个 Amazon S3 位置。您可以在源位置指定的路径中使用通配符 ( * )，以上传路径与通配符模式匹配的所有文件。

如果递归 S3Upload 操作失败，已上传的任何文件都将保留在目标 Amazon S3 存储桶中。

支持的使用案例

IAM 要求

与实例配置文件关联的 IAM 角色必须具有运行 S3Upload 操作模块的权限。必须将以下 IAM 策略附加到与实例配置文件关联的 IAM 角色。该策略必须向目标 Amazon S3 存储桶授予 s3:PutObject 权限。例如， arn:aws:s3::: BucketName /* ）。

输入示例：将具有键前缀的 Amazon S3 存储桶中的所有文件复制到本地文件夹

以下示例展示了如何将本地文件夹中的所有文件复制到带有键前缀的 Amazon S3 存储桶中。该示例不会复制子文件夹或其内容，因为未指定 recurse ，并且它默认为 false 。

  - name: MyS3UploadMultipleFiles
    action: S3Upload
    onFailure: Abort
    maxAttempts: 3
    inputs:
      - source: C:\myfolder\*
        destination: s3://mybucket/path/to/
        expectedBucketOwner: 123456789022

输入示例：将所有文件和文件夹从本地文件夹递归复制到 Amazon S3 存储桶

以下示例展示了如何将所有文件和文件夹从本地文件夹递归复制到带有键前缀的 Amazon S3 存储桶中。

  - name: MyS3UploadFolder
    action: S3Upload
    onFailure: Abort
    maxAttempts: 3
    inputs:
      - source: C:\myfolder\*
        destination: s3://mybucket/path/to/
        recurse: true
        expectedBucketOwner: 123456789022

WebDownload

WebDownload 操作模块允许您通过 HTTP/HTTPS 协议从远程位置下载文件和资源（ 建议使用 HTTP S）。对下载数量或大小没有限制。该模块处理重试和指数回退逻辑。

根据用户输入，每次下载操作最多可尝试 5 次。这些尝试与 steps 文档的 maxAttempts 字段中指定的尝试不同，而是与操作模块失败有关。

此操作模块隐式处理重定向。除 200 外，所有 HTTP 状态代码都会引发错误。

输入示例：将远程文件下载到本地目标

  - name: DownloadRemoteFile
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://testdomain/path/to/java14.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/

输入示例：下载一个远程文件而不覆盖本地目标，然后下载另一个带有文件验证功能的远程文件

  - 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

输入示例：下载远程文件并忽略 SSL 认证验证

  - name: DownloadRemoteIgnoreValidation
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://www.bad-ssl.com/resource
        destination: /tmp/downloads/
        ignoreCertificateErrors: true

文件系统操作模块

下一节详细介绍了执行文件系统操作命令和说明的操作模块。

AppendFile

AppendFile 操作模块将指定内容添加到文件中先前存在的内容中。

如果文件编码值与默认编码 ( utf-8 ) 值不同，可以使用 encoding 选项指定文件编码值。默认情况下， utf-16 和 utf-32 使用小端字节序编码。

发生以下情况时，操作模块会返回错误：

输入示例：附加文件而不编码（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

CopyFile 操作模块将文件从指定源复制到指定目标。默认情况下，如果目标文件夹在运行时不存在，该模块将会以递归方式创建该文件夹。

如果指定文件夹中已存在具有指定名称的文件，则默认情况下，操作模块将覆盖现有文件。您可以将覆盖选项设置为 false ，覆盖这一默认行为。当覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。此选项的工作原理与 Linux 中的 cp 命令相同，默认情况下会覆盖。

源文件名可以包含通配符 ( * )。只有在最后一个文件路径分隔符（ / 或 \ ）之后才可使用通配符。如果源文件名中包含通配符，则所有与通配符匹配的文件都将复制到目标文件夹。如果要使用通配符移动多个文件，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾，这表示目标输入是一个文件夹。

如果目标文件名与源文件名不同，则可以使用 destination 选项指定目标文件名。如果未指定目标文件名，则使用源文件的名称来创建目标文件。最后一个文件路径分隔符（ / 或 \ ）之后的任何文本都将视为文件名。如果要使用与源文件相同的文件名，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾。

发生以下情况时，操作模块会返回错误：

输入示例：复制文件而不覆盖（Windows）

  - name: CopyingFilesWithoutOverwriteWindows
    action: CopyFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder\destinationFile.txt
        overwrite: false

CopyFolder

CopyFolder 操作模块将文件夹从指定源复制到指定目标。 source 选项的输入为要复制的文件夹， destination 选项的输入为源文件夹内容被复制的文件夹。默认情况下，如果目标文件夹在运行时不存在，该模块将会以递归方式创建该文件夹。

如果指定文件夹中已经存在具有指定名称的文件夹，则默认情况下，操作模块会覆盖现有文件夹。您可以将覆盖选项设置为 false ，覆盖这一默认行为。如果将覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。

源文件夹名称可以包含通配符 ( * )。只有在最后一个文件路径分隔符（ / 或 \ ）之后才可使用通配符。如果源文件夹名称中包含通配符，则所有与通配符匹配的文件夹都将复制到目标文件夹。如果要使用通配符复制多个文件夹，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾，这表示目标输入是一个文件夹。

如果目标文件夹名称与源文件夹名称不同，则可以使用 destination 选项指定目标文件夹名称。如果未指定目标文件夹名称，则使用源文件夹的名称来创建目标文件夹。最后一个文件路径分隔符（ / 或 \ ）之后的任何文本都将视为文件夹名称。如果要使用与源文件夹相同的文件夹名称，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾。

发生以下情况时，操作模块会返回错误：

输入示例：使用源文件夹名称复制文件夹（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

CreateFile 操作模块在指定位置创建文件。默认情况下，如有需要，该模块还会以递归方式创建父文件夹。

如果指定文件夹中已存在该文件，则默认情况下，操作模块会截断或覆盖现有文件。您可以将覆盖选项设置为 false ，覆盖这一默认行为。当覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。

如果文件编码值与默认编码 ( utf-8 ) 值不同，可以使用 encoding 选项指定文件编码值。默认情况下， utf-16 和 utf-32 使用小端字节序编码。

owner 、 group 、和 permissions 是可选输入。 permissions 的输入必须是字符串值。如果未提供默认值，将使用默认值创建文件。Windows 平台不支持这些选项。如果在 Windows 平台上使用选项 owner 、 group 和 permissions ，则此操作模块将验证并返回错误。

此操作模块可以创建一个文件，其权限由操作系统的默认 umask 值定义。如果想覆盖默认值，则必须设置 umask 值。

发生以下情况时，操作模块会返回错误：

输入示例：创建文件而不覆盖（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: <skip section file name>

有关更多信息，请参阅 覆盖 Linux 清理脚本

CreateFolder 操作模块在指定位置创建一个文件夹。默认情况下，如有需要，该模块还会以递归方式创建父文件夹。

如果指定文件夹中已存在该文件夹，则默认情况下，操作模块会截断或覆盖现有文件夹。您可以将覆盖选项设置为 false ，覆盖这一默认行为。如果将覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。

owner 、 group 、和 permissions 是可选输入。 permissions 的输入必须是字符串值。Windows 平台不支持这些选项。如果在 Windows 平台上使用选项 owner 、 group 和 permissions ，则此操作模块将验证并返回错误。

此操作模块可以创建一个文件夹，其权限由操作系统的默认 umask 值定义。如果想覆盖默认值，则必须设置 umask 值。

发生以下情况时，操作模块会返回错误：

CreateSymlink 操作模块创建符号链接或包含对另一个文件的引用的文件。Windows 平台不支持此模块。

path 和 target 选项的输入可以是绝对路径，也可以是相对路径。如果 path 选项的输入是相对路径，则在创建链接时它将替换为绝对路径。

默认情况下，当指定文件夹中已存在具有指定名称的链接时，操作模块会返回错误。您可以将 force 选项设置为 true ，覆盖这一默认行为。当 force 选项设置为 true 时，模块将覆盖现有链接。

如果父文件夹不存在，则默认情况下，操作模块会以递归方式创建该文件夹。

发生以下情况时，操作模块会返回错误：

DeleteFile 操作模块删除指定位置的一个或多个文件。

path 的输入应该是有效的文件路径或文件名中带有通配符 ( * ) 的文件路径。如果在文件名中已指定通配符，则同一文件夹中与通配符匹配的所有文件都将被删除。

发生以下情况时，操作模块会返回错误：

DeleteFolder 操作模块删除文件夹。

如果该文件夹不为空，则必须将 force 选项设置为 true 才能删除该文件夹及其内容。如果您未将 force 选项设置为 true ，并且您要删除的文件夹不为空，则操作模块会返回错误。 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\

ListFiles 操作模块列出了指定文件夹中的文件。当递归选项设置为 true 时，将列出子文件夹中的文件。默认情况下，此模块不列出子文件夹中的文件。

要列出名称与指定模式匹配的所有文件，请使用 fileNamePattern 选项提供该模式。 fileNamePattern 选项接受通配符 ( * ) 值。提供 fileNamePattern 时，将返回与指定文件名格式匹配的所有文件。

发生以下情况时，操作模块会返回错误：

MoveFile 操作模块将文件从指定源移动到指定目标。

如果指定文件夹中已存在该文件，则默认情况下，操作模块会覆盖现有文件。您可以将覆盖选项设置为 false ，覆盖这一默认行为。当覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件时，操作模块将返回错误。此选项的工作原理与 Linux 中的 mv 命令相同，默认情况下会覆盖。

源文件名可以包含通配符 ( * )。只有在最后一个文件路径分隔符（ / 或 \ ）之后才可使用通配符。如果源文件名中包含通配符，则所有与通配符匹配的文件都将复制到目标文件夹。如果要使用通配符移动多个文件，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾，这表示目标输入是一个文件夹。

如果目标文件名与源文件名不同，则可以使用 destination 选项指定目标文件名。如果未指定目标文件名，则使用源文件的名称来创建目标文件。最后一个文件路径分隔符（ / 或 \ ）之后的任何文本都将视为文件名。如果要使用与源文件相同的文件名，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾。

发生以下情况时，操作模块会返回错误：

输入示例：使用源文件名移动文件（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

MoveFolder

MoveFolder 操作模块将文件夹从指定源移动到指定目标。 source 选项的输入是要移动的文件夹，而 destination 选项的输入是源文件夹内容被移动的文件夹。

如果目标父文件夹或 destination 选项的输入在运行时不存在，则默认情况下，模块会在指定的目标上递归创建文件夹。

如果目标文件夹中已存在与源文件夹相同的文件夹，则默认情况下，操作模块会覆盖现有文件夹。您可以将覆盖选项设置为 false ，覆盖这一默认行为。如果将覆盖选项设置为 false ，并且在指定位置已经存在具有指定名称的文件夹，操作模块将返回错误。

源文件夹名称可以包含通配符 ( * )。只有在最后一个文件路径分隔符（ / 或 \ ）之后才可使用通配符。如果源文件夹名称中包含通配符，则所有与通配符匹配的文件夹都将复制到目标文件夹。如果要使用通配符移动多个文件夹，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾，这表示目标输入是一个文件夹。

如果目标文件夹名称与源文件夹名称不同，则可以使用 destination 选项指定目标文件夹名称。如果未指定目标文件夹名称，则使用源文件夹的名称来创建目标文件夹。最后一个文件路径分隔符（ / 或 \ ）之后的任何文本都将视为文件夹名称。如果要使用与源文件夹相同的文件夹名称，则 destination 选项的输入必须以文件路径分隔符（ / 或 \ ）结尾。

发生以下情况时，操作模块会返回错误：

输入示例：使用源文件夹名称移动文件夹（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

ReadFile

ReadFile 操作模块读取字符串类型的文本文件的内容。该模块可用于读取文件内容，以便通过链接在后续步骤中使用，或者用于读取数据到 console.log 文件。如果指定的路径是符号链接，则此模块将返回目标文件的内容。该模块仅支持文本文件。

如果文件编码值与默认编码 ( utf-8 ) 值不同，可以使用 encoding 选项指定文件编码值。默认情况下， utf-16 和 utf-32 使用小端字节序编码。

默认情况下，此模块无法将文件内容打印到 console.log 文件中。您可以通过将 printFileContent 属性设置为 true 来覆盖此设置。

该模块只能返回文件的内容。该模块无法解析文件（例如 Excel 或 JSON 文件）。

发生以下情况时，操作模块会返回错误：

输入示例：读取文件（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

SetFileEncoding

SetFileEncoding 操作模块修改现有文件的编码属性。该模块可以将文件编码从 utf-8 转换为指定的编码标准。默认情况下， utf-16 和 utf-32 为小端字节序编码。

发生以下情况时，操作模块会返回错误：

输入示例：设置文件编码属性

  - name: SettingFileEncodingProperty
    action: SetFileEncoding
    inputs:
      - path: /home/UserName/SampleFile.txt
        encoding: UTF-16

SetFileOwner

SetFileOwner 操作模块修改现有文件的 owner 和 group 所有者属性。如果指定文件是符号链接，则模块将修改源文件的 owner 属性。Windows 平台不支持此模块。

该模块接受用户名和组名作为输入。如果未提供组名，则该模块会将文件的组所有者分配给该用户所属的组。

发生以下情况时，操作模块会返回错误：

SetFolderOwner

SetFolderOwner 操作模块以递归方式修改现有文件夹的 owner 和 group 所有者属性。默认情况下，该模块可以修改文件夹中所有内容的所有权。您可以将 recursive 选项设置为 false 以覆盖此行为。Windows 平台不支持此模块。

该模块接受用户名和组名作为输入。如果未提供组名，则该模块会将文件的组所有者分配给该用户所属的组。

发生以下情况时，操作模块会返回错误：

输入示例：设置文件夹所有者属性而不覆盖文件夹中所有内容的所有权

  - name: SettingFolderPropertyWithOutRecursively
    action: SetFolderOwner
    inputs:
      - path: /SampleFolder/
        owner: LinuxUser
        recursive: false

输入示例：通过指定用户组名称来设置文件所有权属性

  - name: SettingFolderPropertyWithGroup
    action: SetFolderOwner
    inputs:
      - path: /SampleFolder/
        owner: LinuxUser
        group: LinuxUserGroup

SetFilePermissions 操作模块修改现有文件的。 permissions Windows 平台不支持此模块。

permissions 的输入必须是字符串值。

此操作模块将创建一个文件，其权限由操作系统默认的 umask 值定义。如果想覆盖默认值，则必须设置 umask 值。

发生以下情况时，操作模块会返回错误：

SetFolderPermissions

SetFolderPermissions 操作模块以递归方式修改现有文件夹及其所有子文件和子文件夹。 permissions 默认情况下，此模块可以修改指定文件夹中所有内容的权限。您可以将 recursive 选项设置为 false 以覆盖此行为。Windows 平台不支持此模块。

permissions 的输入必须是字符串值。

此操作模块可以根据操作系统的默认 umask 值修改权限。如果想覆盖默认值，则必须设置 umask 值。

发生以下情况时，操作模块会返回错误：

输入示例：设置文件夹权限而不修改文件夹所有内容的权限

  - name: SettingFolderPermissionsNoRecursive
    action: SetFolderPermissions
    inputs:
      - path: /home/UserName/SampleFolder/
        permissions: 777
        recursive: false

您可以在字符串的外部使用单引号（'）来包含它，并在字符串内部使用双引号（"），如下面的示例所示。

properties:
  COMPANYNAME: '"Acme ""Widgets"" and ""Gizmos."""'

在这种情况下，如果您需要在字符串中使用撇号，则必须对其进行转义。这意味着需要在撇号前使用另一个单引号（'）。

你可以在字符串的外面使用双引号（"）来包含它。您可以使用反斜杠字符 ( \ ) 对字符串中的任何双引号进行转义，如以下示例所示。

properties:
  COMPANYNAME: "\"Acme \"\"Widgets\"\" and \"\"Gizmos.\"\"\""

这两种方法都将值 COMPANYNAME="Acme ""Widgets"" and ""Gizmos.""" 传递给 msiexec 命令。

安装 MSI

InstallMSI 操作模块使用 MSI 文件安装 Windows 应用程序。您可以使用本地路径、S3 对象 URI 或 Web URL 来指定 MSI 文件。重新启动选项可配置系统的重新启动行为。

AWSTOE 根据操作模块的输入参数生成 msiexec 命令。 path （MSI 文件位置）和 logFile （日志文件位置）输入参数的值必须用引号（"）括起来。

以下 MSI 退出代码视为成功：

Allow ：如果 msiexec 命令返回退出代码，表示需要重新启动，则启动系统重启。

Skip ：在 console.log 文件中记录一条信息性消息，表示跳过了重新启动。即使 msiexec 命令返回表示需要重新启动的退出代码，该选项也可防止重新启动。

指定用于 MSI 安装日志的选项。指定的标志与 /L 命令行参数一起传递给 MSI 安装程序，以启用日志记录。如果未指定任何标志，则 AWSTOE 使用默认值。

有关 MSI 日志选项的更多信息，请参阅 Microsoft Windows Installer 产品文档中的 命令行选项 。

日志文件位置的绝对路径或相对路径。如果该日志文件路径不存在，请创建它。如果未提供日志文件路径，则 AWSTOE 不存储 MSI 安装日志。

MSI 日志属性键值对，例如： TARGETDIR: "C:\target\location"

注意：不允许修改以下属性：

忽略路径中指定的安装程序的 authenticode 签名验证错误的标志。 Get-AuthenticodeSignature 命令用于验证安装程序。

true ：忽略验证错误并运行安装程序。

false ：不忽略验证错误。仅当验证成功时，安装程序才会运行。这是默认行为。

允许运行路径中指定的未签名安装程序的标志。 Get-AuthenticodeSignature 命令用于验证安装程序。

true ：忽略 Get-AuthenticodeSignature 命令返回的 NotSigned 状态并运行安装程序。

false ：需要对安装程序进行签名。未签名的安装程序将无法运行。这是默认行为。

输入示例：Amazon S3 路径安装

- name: s3-path-install
  steps:
    - name: S3PathInstaller
      action: InstallMSI
      inputs:
        path: s3://<bucket-name>/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://<some-path>/sample.msi
        logFile: web-path-install.log
        reboot: Skip
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: false

以下是 InstallMSI 操作模块的输出示例。

卸载 MSI

UninstallMSI 操作模块允许您使用 MSI 文件删除 Windows 应用程序。您可以使用本地文件路径、S3 对象 URI 或 Web URL 指定 MSI 文件位置。重新启动选项可配置系统的重新启动行为。

AWSTOE 根据操作模块的输入参数生成 msiexec 命令。生成 msiexec 命令时，MSI 文件位置 ( path ) 和日志文件位置 ( logFile ) 将明确用双引号（"）括起来。

以下 MSI 退出代码视为成功：

Allow ：如果 msiexec 命令返回退出代码，表示需要重新启动，则启动系统重启。

Skip ：在 console.log 文件中记录一条信息性消息，表示跳过了重新启动。即使 msiexec 命令返回表示需要重新启动的退出代码，该选项也可防止重新启动。

指定用于 MSI 安装日志的选项。指定的标志与 /L 命令行参数一起传递给 MSI 安装程序，以启用日志记录。如果未指定任何标志，则 AWSTOE 使用默认值。

有关 MSI 日志选项的更多信息，请参阅 Microsoft Windows Installer 产品文档中的 命令行选项 。

日志文件位置的绝对路径或相对路径。如果该日志文件路径不存在，请创建它。如果未提供日志文件路径，则 AWSTOE 不存储 MSI 安装日志。

MSI 日志属性键值对，例如： TARGETDIR: "C:\target\location"

注意：不允许修改以下属性：

忽略路径中指定的安装程序的 authenticode 签名验证错误的标志。 Get-AuthenticodeSignature 命令用于验证安装程序。

true ：忽略验证错误并运行安装程序。

false ：不忽略验证错误。仅当验证成功时，安装程序才会运行。这是默认行为。

允许运行路径中指定的未签名安装程序的标志。 Get-AuthenticodeSignature 命令用于验证安装程序。

true ：忽略 Get-AuthenticodeSignature 命令返回的 NotSigned 状态并运行安装程序。

false ：需要对安装程序进行签名。未签名的安装程序将无法运行。这是默认行为。

输入示例：移除 Amazon S3 路径安装

- name: s3-path-uninstall
  steps:
    - name: S3PathUninstaller
      action: UninstallMSI
      inputs:
        path: s3://<bucket-name>/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://<some-path>/sample.msi
        logFile: web-path-uninstall.log
        reboot: Skip
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: false

以下是 UninstallMSI 操作模块的输出示例。

系统操作模块

下一部分介绍了执行文件系统操作命令和说明的操作模块。

Reboot

重启 操作模块重新引导实例。它具有一个可配置的选项以延迟启动重新引导。默认情况下， delaySeconds 设置为 0 ，表示没有延迟。由于在实例重启时步骤超时不适用，因此重启操作模块不支持步骤超时。

如果该应用程序是由 Systems Manager 代理调用的，则向 Systems Manager 代理返回退出代码（Windows 为 3010 ，Linux 为 194 ）。Systems Manager 代理处理系统重新引导，如 从脚本中重新引导托管实例 中所述。

如果该应用程序是在主机上作为单独进程调用的，它将保存当前执行状态，配置重新引导后自动运行触发器以重新执行该应用程序，然后重新引导系统。

重新引导后自动运行触发器：

Linux ： AWSTOE 在 crontab 中添加了一个在系统重启后自动运行的作业。

@reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml

在该应用程序启动时，将清除该触发器。

要使用 Reboot 操作模块，对于包含重新引导 exitcode 的步骤（例如， 3010 ），您必须以 sudo user 形式运行应用程序二进制文件。

SetRegistry

SetRegistry 操作模块接受输入列表，并允许您设置指定注册表项的值。如果注册表项不存在，则会在定义的路径中创建该注册表项。该功能仅适用于 Windows。

UpdateOS

UpdateOS 操作模块增加了对安装 Windows 和 Linux 更新的支持。默认情况下会安装所有可用更新。或者，您可以为待安装的操作模块配置一个或多个特定更新的列表。您也可以指定要从安装中排除的更新。

如果同时提供了“包括”和“排除”列表，则更新的结果列表只能包含在“包括”列表中列出并且在“排除”列表中未列出的那些更新。

Windows 。更新是从目标计算机上配置的更新源中安装的。

Linux 。该应用程序检查 Linux 平台中支持的软件包管理器，并使用 yum 或 apt-get 软件包管理器。如果不支持这两个软件包管理器，则会返回错误。你应当拥有运行 UpdateOS 操作模块的 sudo 权限。如果您没有 sudo 权限，则会返回 error.Input 。

对于 Windows，可以指定以下值：

您可以指定一个或多个 Microsoft 知识库 (KB) 文章 ID 以包括在可以安装的更新列表中。有效的格式为 KB1234567 或 1234567 。

使用通配符值 ( * ) 的更新名称。有效的格式为 Security* 或 *Security* 。

对于 Linux，您可以指定一个或多个要包括在安装的更新列表中的软件包。

对于 Windows，可以指定以下值：

您可以指定一个或多个 Microsoft 知识库 (KB) 文章 ID 以包括在要从安装中排除的更新列表中。有效的格式为 KB1234567 或 1234567 。

使用通配符 ( * ) 值的更新名称。有效的格式为： Security* 或 *Security* 。

对于 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*'