amazon.aws.s3_object 模块 – 管理 S3 中的对象

注意

此模块是 amazon.aws 集合 (版本 9.0.0) 的一部分。

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

要安装它，请使用：ansible-galaxy collection install amazon.aws。您需要其他要求才能使用此模块，请参阅 需求 获取详细信息。

要在 playbook 中使用它，请指定：amazon.aws.s3_object。

amazon.aws 1.0.0 中的新增功能

概要

• 此模块允许用户管理 S3 存储桶中的对象和目录。包括对创建和删除对象和目录、将对象检索为文件或字符串、生成下载链接以及复制已存储在 Amazon S3 中的对象的支持。

• 可以使用 amazon.aws.s3_bucket 模块创建或删除 S3 存储桶。

• 兼容 AWS、DigitalOcean、Ceph、Walrus、FakeS3 和 StorageGRID。

• 使用非 AWS 服务时，应指定 endpoint_url。

注意

此模块具有相应的 action 插件。

别名：aws_s3

需求

执行此模块的主机需要以下需求。

• python >= 3.6

• boto3 >= 1.28.0

• botocore >= 1.31.0

参数

参数	注释
access_key 别名：aws_access_key_id, aws_access_key, ec2_access_key 字符串	AWS 访问密钥 ID。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 还可以按优先级递减的顺序使用 AWS_ACCESS_KEY_ID、AWS_ACCESS_KEY 或 EC2_ACCESS_KEY 环境变量。 aws_access_key 和 profile 选项是互斥的。 aws_access_key_id 别名在 5.1.0 版本中添加，以与 AWS botocore SDK 保持一致。 ec2_access_key 别名已弃用，将在 2024-12-01 之后的一个版本中删除。 EC2_ACCESS_KEY 环境变量的支持已弃用，将在 2024-12-01 之后的一个版本中删除。
aws_ca_bundle 路径	验证 SSL 证书时要使用的 CA 捆绑包的位置。 还可以使用 AWS_CA_BUNDLE 环境变量。
aws_config 字典	用于修改 botocore 配置的字典。 可以在 AWS 文档中找到参数 https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config。
bucket 字符串 / 必需	存储桶名称。
ceph 别名：rgw 布尔值	启用与 Ceph RGW 的 API 兼容性。 它考虑了与 Ceph 一起工作的 S3 API 子集，以便在可能的情况下提供相同的模块行为。 如果 ceph=true，则需要 endpoint_url。 选项 false ← (默认) true
content 字符串 amazon.aws 1.3.0 中新增	要 put 到对象中的内容。 参数值将被视为字符串，并在发送到 S3 之前转换为 UTF-8。 要发送二进制数据，请改用 content_base64 参数。 当 mode=put 时，必须指定 content、content_base64 或 src 之一，否则将被忽略。
content_base64 字符串 amazon.aws 1.3.0 中新增	要 put 到对象中的 base64 编码二进制数据。 如果您需要放置原始二进制数据，请使用此方法，并且不要忘记进行 base64 编码。 当 mode=put 时，必须指定 content、content_base64 或 src 之一，否则将被忽略。
copy_src 字典 amazon.aws 2.0.0 中新增	要复制的对象的源详细信息。 如果 mode=copy，则需要此参数。
bucket 字符串 / 必需	源存储桶的名称。
object 字符串	源对象的键名。 如果未指定，则 copy_src.bucket 的所有对象都将复制到指定的存储桶中。
prefix 字符串 amazon.aws 6.2.0 中新增	复制以指定前缀开头的所有键。 如果提供了 copy_src.object，则忽略此参数。 默认值： ""
version_id 字符串	源对象的版本 ID。
debug_botocore_endpoint_logs 布尔值	使用 botocore.endpoint 日志记录器解析任务期间进行的唯一（而非总数）"resource:action" API 调用，并将结果集输出到任务结果的 resource_actions 密钥中。使用 aws_resource_action 回调函数将总数输出到 playbook 中。 也可以使用 ANSIBLE_DEBUG_BOTOCORE_LOGS 环境变量。 选项 false ← (默认) true
dest 路径	当 mode=get 时，下载对象/密钥的目标文件路径。 当 mode 不是 get 时忽略。
dualstack 布尔值	启用 Amazon S3 双栈端点，允许使用 IPv4 和 IPv6 进行 S3 通信。 同时传递 dualstack 和 endpoint_url 的支持已被弃用，双栈端点将使用已配置的 region 自动配置。该支持将在 2024-12-01 之后的一个版本中移除。 选项 false ← (默认) true
encrypt 布尔值	当 mode=put 或 mode=copy 时，请求对象的服务器端加密。 当 mode 既不是 put 也不是 copy 时忽略。 选项 false true ← (默认)
encryption_kms_key_id 字符串	使用 encryption_mode=aws:kms 加密对象时使用的 KMS 密钥 ID。 如果 encryption_mode 不是 aws:kms，则忽略。
encryption_mode 字符串	如果 encrypt=true，则使用的加密模式。 选项 "AES256" ← (默认) "aws:kms"
endpoint_url 别名：ec2_url, aws_endpoint_url, s3_url 字符串	连接到非默认 AWS 端点的 URL。虽然这可以用于连接到其他兼容 AWS 的服务，但 amazon.aws 和 community.aws 集合只经过 AWS 的测试。 也可以使用 AWS_URL 或 EC2_URL 环境变量，优先级依次递减。 ec2_url 和 s3_url 别名已被弃用，并将 2024-12-01 之后的一个版本中移除。 EC2_URL 环境变量的支持已被弃用，并将 2024-12-01 之后的一个版本中移除。
expected_bucket_owner 字符串 在 amazon.aws 8.2.0 中添加	预期存储桶所有者的帐户 ID。 如果提供的帐户 ID 与存储桶的实际所有者不匹配，则请求将失败并返回 HTTP 状态代码 403 Forbidden（访问被拒绝）。
expiry 别名：expiration 整数	执行 mode=put 或 mode=geturl 操作时，S3/Walrus 生成的 URL 的时间限制（以秒为单位）。 当 mode 既不是 put 也不是 geturl 时忽略。 默认： 600
headers 字典	当 mode=put 时使用的自定义标头，为键值对字典。 当 mode 不是 put 时忽略。
ignore_nonexistent_bucket 布尔值	如果存储桶或 IAM 策略具有限制性，则覆盖初始存储桶查找。 当用户可能具有 GetObject 权限但没有其他权限时，这很有用。在这种情况下，除非指定 ignore_nonexistent_bucket=true，否则使用 mode=get 将失败。 选项 false ← (默认) true
marker 字符串	使用列表模式时指定要开始的密钥。对象密钥按字母顺序返回，从标记后的下一个密钥开始。
max_keys 整数	当 mode=list 时返回的结果最大数量。 如果未设置，将返回**所有**密钥。 当 mode 不是 list 时忽略。
metadata 字典	当 mode=put 或 mode=copy 时使用的元数据，为键值对字典。
mode 字符串 / 必需	切换模块行为： put：上传 get：下载 geturl：返回下载 URL getstr：将对象下载为字符串 list：列出密钥 create：创建存储桶目录 delobj：删除对象 copy：复制已存储在另一个存储桶中的对象 6.0.0 版本中移除了创建和删除存储桶的支持。要创建和管理存储桶本身，请使用 amazon.aws.s3_bucket 模块。 list 的支持已被弃用，并将 2026-11-01 之后的一个版本中移除。应使用 amazon.aws.s3_object_info 模块代替 list。 选项 "get" "put" "create" "geturl" "getstr" "delobj" "list" "copy"
object 字符串	存储桶内对象的密钥名称。 可用于创建“虚拟目录”，参见示例。 对象密钥名称不应包含前导 /，更多信息请参见 https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html。 传递前导 / 的支持已被弃用，并将 2025-12-01 之后的一个版本中移除。
overwrite 别名：force 字符串	强制覆盖本地文件系统或远程对象/密钥。 当 mode=put 或 mode=get 时使用。 当 mode 既不是 put 也不是 get 时忽略。 必须是布尔值、always、never、different 或 latest。 true 等同于 always。 false 等同于 never。 如果将其设置为different，则会将本地文件的 MD5 校验和与 S3 中的对象/密钥的“ETag”进行比较。“ETag”可能是也可能不是对象数据的 MD5 散列。有关 ETag 响应标头的更多信息，请参见此处 https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html。 当mode=get 且 overwrite=latest 时，将比较本地文件的最后修改时间戳与 S3 中的对象/密钥的“LastModified”。 默认值： "different"
权限 列表 / 元素=字符串	此选项允许用户设置创建的对象/存储桶上的预定义权限。可以设置的权限包括：对于存储桶：private、public-read、public-read-write、authenticated-read；对于对象：private、public-read、public-read-write、aws-exec-read、authenticated-read、bucket-owner-read、bucket-owner-full-control。可以将多个权限指定为列表；但在初始文件上传过程中，只会使用第一个权限。 有关权限的完整列表，请参见 AWS 文档 https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl。 选项 "private" ← (默认值) "public-read" "public-read-write" "aws-exec-read" "authenticated-read" "bucket-owner-read" "bucket-owner-full-control" 默认值： ["private"]
prefix 字符串	将响应限制为以指定前缀开头的密钥（列表模式）。 默认值： ""
profile 别名：aws_profile 字符串	用于身份验证的命名 AWS 配置文件。 有关命名配置文件的更多信息，请参见 AWS 文档 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html。 也可以使用AWS_PROFILE环境变量。 profile选项与aws_access_key、aws_secret_key和security_token选项互斥。
purge_tags 布尔值	如果purge_tags=true 且设置了tags，则将从资源中清除现有标签，以完全匹配tags参数定义的内容。 如果没有设置tags参数，则即使purge_tags=True，也不会修改标签。 以aws:开头的标签键由 Amazon 保留，无法修改。因此，在purge_tags参数中，它们将被忽略。有关更多信息，请参见 Amazon 文档 https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions。 选项 false true ← (默认)
region 别名：aws_region，ec2_region 字符串	要使用的 AWS 区域。 对于 IAM、Route53 和 CloudFront 等全局服务，将忽略region。 也可以使用AWS_REGION或EC2_REGION环境变量。 有关更多信息，请参见 Amazon AWS 文档 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region。 别名ec2_region已弃用，将在 2024 年 12 月 1 日之后的版本中删除。 对EC2_REGION环境变量的支持已弃用，将在 2024 年 12 月 1 日之后的版本中删除。
retries 别名：retry 整数	在可恢复的故障发生时，在实际失败之前要重试多少次。 默认值： 0
secret_key 别名：aws_secret_access_key，aws_secret_key，ec2_secret_key 字符串	AWS 密钥。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以按优先级递减顺序使用AWS_SECRET_ACCESS_KEY、AWS_SECRET_KEY或EC2_SECRET_KEY环境变量。 secret_key和profile选项互斥。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了aws_secret_access_key别名。 别名ec2_secret_key已弃用，将在 2024 年 12 月 1 日之后的版本中删除。 对EC2_SECRET_KEY环境变量的支持已弃用，将在 2024 年 12 月 1 日之后的版本中删除。
session_token 别名：aws_session_token，security_token，aws_security_token，access_token 字符串	与临时凭据一起使用的 AWS STS 会话令牌。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以按优先级递减顺序使用AWS_SESSION_TOKEN、AWS_SECURITY_TOKEN或EC2_SECURITY_TOKEN环境变量。 security_token和profile选项互斥。 在 3.2.0 版本中添加了别名aws_session_token和session_token，在 6.0.0 版本中，参数名称从security_token更改为session_token。 别名security_token、aws_security_token和access_token已弃用，将在 2024 年 12 月 1 日之后的版本中删除。 对EC2_SECRET_KEY和AWS_SECURITY_TOKEN环境变量的支持已弃用，将在 2024 年 12 月 1 日之后的版本中删除。
sig_v4 布尔值 在 amazon.aws 5.0.0 中添加	强制 Boto SDK 使用签名版本 4。 仅适用于获取模式，mode=get、mode=getstr、mode=geturl。 选项 false true ← (默认)
src 路径	执行put操作时的源文件路径。 当 mode=put 时，必须指定 content、content_base64 或 src 之一，否则将被忽略。
tags 别名：resource_tags 字典	表示要应用于资源的标签的字典。 如果没有设置tags参数，则不会修改标签。
validate_bucket_name 布尔值 在 amazon.aws 3.1.0 中添加	存储桶名称是否应经过验证以符合 AWS S3 命名规则。 默认情况下启用，对于不强制执行这些规则的 S3 后端，可以禁用此选项。 有关存储桶命名规则的更多信息，请参见 Amazon 文档 https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html。 选项 false true ← (默认)
validate_certs 布尔值	如果设置为false，则不会验证与 AWS API 通信的 SSL 证书。 强烈建议不要设置validate_certs=false，作为替代方法，请考虑改为设置aws_ca_bundle。 选项 false true ← (默认)
version 字符串	存储桶内对象的版本 ID。如果在目标存储桶中启用了版本控制，则可以使用它来获取文件的特定版本。

备注

注意

• 对tags和purge_tags的支持是在 2.0.0 版本中添加的。

• 在 5.0.0 版本中，s3_url参数已合并到endpoint_url参数中，s3_url仍然是endpoint_url的别名。

• 对于 Walrus，endpoint_url应设置为端点的 FQDN，不包含方案和路径。

• 对环境变量S3_URL的支持已弃用，并将在2024-12-01之后的一个版本中移除。请使用endpoint_url参数或环境变量AWS_URL。

• 在6.0.0版本中移除了创建和删除存储桶的支持。

• 注意：对于模块，环境变量和配置文件是从Ansible的“主机”上下文读取的，而不是“控制器”上下文。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从Ansible的“控制器”上下文读取的，而不是“主机”上下文。

• Ansible使用的AWS SDK (boto3)也可能从Ansible“主机”上下文中的配置文件（通常为~/.aws/credentials）读取凭据和其他设置（如区域）的默认值。更多信息，请参见https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。

示例

- name: Simple PUT operation
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put

- name: PUT operation from a rendered template
  amazon.aws.s3_object:
    bucket: mybucket
    object: /object.yaml
    content: "{{ lookup('template', 'templates/object.yaml.j2') }}"
    mode: put

- name: Simple PUT operation in Ceph RGW S3
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    ceph: true
    endpoint_url: "https://127.0.0.1:8000"

- name: Simple GET operation
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    dest: /usr/local/myfile.txt
    mode: get

- name: Get a specific version of an object.
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    version: 48c9ee5131af7a716edc22df9772aa6f
    dest: /usr/local/myfile.txt
    mode: get

- name: PUT/upload with metadata
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    metadata:
      Content-Encoding: gzip
      Cache-Control: no-cache

- name: PUT/upload with custom headers
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    src: /usr/local/myfile.txt
    mode: put
    headers: '[email protected]'

- name: List keys simple
  amazon.aws.s3_object:
    bucket: mybucket
    mode: list

- name: List keys all options
  amazon.aws.s3_object:
    bucket: mybucket
    mode: list
    prefix: /my/desired/
    marker: /my/desired/0023.txt
    max_keys: 472

- name: GET an object but don't download if the file checksums match. New in 2.0
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    dest: /usr/local/myfile.txt
    mode: get
    overwrite: different

- name: Delete an object from a bucket
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    mode: delobj

- name: Copy an object already stored in another bucket
  amazon.aws.s3_object:
    bucket: mybucket
    object: /my/desired/key.txt
    mode: copy
    copy_src:
      bucket: srcbucket
      object: /source/key.txt

- name: Copy all the objects with name starting with 'ansible_'
  amazon.aws.s3_object:
    bucket: mybucket
    mode: copy
    copy_src:
      bucket: srcbucket
      prefix: 'ansible_'

返回值

常见的返回值已在此处记录，以下是此模块独有的字段：

Key	描述
contents 字符串	对象的字符串内容。 返回：（对于getstr操作） 示例："Hello, world!"
expiry 整数	预签名URL的有效秒数。 返回：（对于geturl操作） 示例：600
msg 字符串	指示操作状态的消息。 返回：始终返回 示例："PUT operation complete"
s3_keys 列表 / 元素=字符串	对象键列表。 返回：（对于list操作） 示例：["prefix1/", "prefix1/key1", "prefix1/key2"]
tags 字典	S3对象的标签。 返回：始终返回 示例：{"Owner": "dev001", "env": "test"}
url 字符串	对象的URL。 返回：（对于put和geturl操作） 示例："https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature>"

作者

• Lester Wade (@lwade)

• Sloane Hertel (@s-hertel)

• Alina Buzachis (@alinabuzachis)

集合链接

• 问题追踪器
• 代码仓库
• 沟通