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。

注意

此模块具有相应的 操作插件。

别名：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 botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_access_key_id 别名。 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 字符串	要连接到的 URL，而不是默认的 AWS 终端节点。虽然这可以用于连接到其他与 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。 选择 "获取" "放置" "创建" "获取URL" "获取字符串" "删除对象" "列表" "复制"
object 字符串	存储桶内对象的键名。 可用于创建“虚拟目录”，请参阅示例。 对象键名不应包含前导 /，有关更多信息，请参阅 https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html。 已弃用支持传递前导 /，将在 2025-12-01 之后的版本中删除。
覆盖 别名: 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=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-01 之后的版本中删除。 已弃用对 EC2_REGION 环境变量的支持，将在 2024-12-01 之后的版本中删除。
retries 别名: retry 整数	在可恢复的故障时，在实际失败之前重试的次数。 默认值: 0
secret_key 别名: aws_secret_access_key, aws_secret_key, ec2_secret_key 字符串	AWS secret access key。 有关访问令牌的更多信息，请参阅 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-01 之后的版本中删除。 已弃用对 EC2_SECRET_KEY 环境变量的支持，将在 2024-12-01 之后的版本中删除。
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-01 之后的版本中删除。 已弃用对 EC2_SECRET_KEY 和 AWS_SECURITY_TOKEN 环境变量的支持，将在 2024-12-01 之后的版本中删除。
sig_v4 布尔值 在 amazon.aws 5.0.0 中添加	强制 Boto SDK 使用签名版本 4。 仅适用于 get 模式， mode=get、 mode=getstr、 mode=geturl。 选择 false true ← (默认)
src 路径	执行 put 操作时的源文件路径。 当 mode=put 时，必须指定 content、content_base64 或 src 之一，否则将被忽略。
tags 别名: resource_tags 字典	表示要应用于资源的标签的字典。 如果未设置 tags 参数，则不会修改标签。
验证存储桶名称 布尔值 在 amazon.aws 3.1.0 中添加	是否应验证存储桶名称以符合 AWS S3 命名规则。 默认情况下启用，对于不强制执行这些规则的 S3 后端，可以禁用此项。 有关存储桶命名规则的更多信息，请参阅 Amazon 文档 https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html。 选择 false true ← (默认)
验证证书 布尔值	当设置为 false 时，与 AWS API 通信时将不验证 SSL 证书。 强烈建议不要设置 validate_certs=false，作为替代方案，请考虑设置 aws_ca_bundle。 选择 false true ← (默认)
version 字符串	存储桶内对象的版本 ID。如果目标存储桶启用了版本控制，则可以使用此 ID 获取文件的特定版本。

注释

注意

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

• 在 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 ‘host’ 上下文而不是 ‘controller’ 上下文读取的。 因此，可能需要将文件显式复制到 ‘host’。对于查找和连接插件，环境变量和配置文件是从 Ansible ‘controller’ 上下文而不是 ‘host’ 上下文读取的。

• Ansible 使用的 AWS SDK (boto3) 也可能会从其在 Ansible ‘host’ 上下文中的配置文件（通常是 ~/.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 操作完成"
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)

集合链接

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