amazon.aws.s3_object_info 模块 – 收集 S3 中对象信息

注意

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

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

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

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

amazon.aws 5.0.0 中的新增功能

概要

• 描述 S3 中的对象。

• 兼容 AWS、DigitalOcean、Ceph、Walrus、FakeS3 和 StorageGRID（目前仅支持 list_keys）。

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

要求

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

• 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_name 字符串 / 必填	包含该对象的存储桶名称。
ceph 别名：rgw 布尔值	启用与 Ceph RGW 的 API 兼容性。 它考虑了与 Ceph 一起使用的 S3 API 子集，以便在可能的情况下提供相同的模块行为。 如果 ceph=true，则需要 endpoint_url。 选项 false ← (默认) true
debug_botocore_endpoint_logs 布尔值	使用 botocore.endpoint 记录器来解析在任务期间进行的唯一（而不是全部）"resource:action" API 调用，并将该集合输出到任务结果中的 resource_actions 密钥。使用 aws_resource_action 回调来输出 playbook 期间进行的全部列表。 也可以使用 ANSIBLE_DEBUG_BOTOCORE_LOGS 环境变量。 选项 false ← (默认) true
dualstack 布尔值	启用 Amazon S3 双栈端点，允许使用 IPv4 和 IPv6 进行 S3 通信。 同时传递 dualstack 和 endpoint_url 的支持已弃用，系统会使用配置的 region 自动配置 dualstack 端点。该支持将在 2024-12-01 之后的一个版本中移除。 选项 false ← (默认) true
endpoint_url 别名：ec2_url, aws_endpoint_url, s3_url 字符串	用于 Ceph、Eucalyptus 和 fakes3 等的 S3 URL 端点。否则假定为 AWS。
marker 字符串 在 amazon.aws 9.0.0 中添加	指定要开始的对象键。对象键按字母顺序返回，从标记后的键开始。
max_keys 整数 在 amazon.aws 9.0.0 中添加	要返回的结果最大数量。如果只想检索部分结果，请设置此值。
object_details 字典	检索请求的 S3 对象详细信息。
attributes_list 列表 / 元素=字符串	应返回的字段/详细信息。 当 object_details.object_attributes=true 时必需。 选项 "ETag" "校验和" "ObjectParts" "存储类别" "对象大小"
object_acl 布尔值	检索 S3 对象 ACL。 选项 false ← (默认) true
object_attributes 布尔值	检索 S3 对象属性。 选项 false ← (默认) true
object_legal_hold 布尔值	检索 S3 对象 legal_hold。 选项 false ← (默认) true
object_lock_configuration 布尔值	检索 S3 对象 lock_configuration。 选项 false ← (默认) true
object_retention 布尔值	检索 S3 对象 retention。 选项 false ← (默认) true
object_tagging 布尔值	检索 S3 对象标签。 选项 false ← (默认) true
object_name 字符串	对象名称。 如果未指定，则返回指定存储桶中所有对象的列表。
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 选项互斥。
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 之后的一个版本中移除。
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-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 之后的一个版本中移除。
validate_certs 布尔值	设置为 false 时，将不会验证与 AWS API 通信的 SSL 证书。 强烈建议不要设置 validate_certs=false，请考虑改用 aws_ca_bundle。 选项 false true ← (默认)

注释

注意

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

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

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

示例

# Note: These examples do not set authentication details, see the AWS Guide for details.

- name: Retrieve a list of objects in S3 bucket
  amazon.aws.s3_object_info:
    bucket_name: MyTestBucket

- name: Retrieve a list of objects in Ceph RGW S3
  amazon.aws.s3_object_info:
    bucket_name: MyTestBucket
    ceph: true
    endpoint_url: "http://localhost:8000"

- name: Retrieve object metadata without object itself
  amazon.aws.s3_object_info:
    bucket_name: MyTestBucket
    object_name: MyTestObjectKey

- name: Retrieve detailed S3 information for all objects in the bucket
  amazon.aws.s3_object_info:
    bucket_name: MyTestBucket
    object_details:
      object_acl: true
      object_attributes: true
      attributes_list:
        - ETag
        - ObjectSize
        - StorageClass

- name: Retrieve detailed S3 object information
  amazon.aws.s3_object_info:
    bucket_name: MyTestBucket
    object_name: MyTestObjectKey
    object_details:
      object_acl: true
      object_tagging: true
      object_legal_hold: true
      object_attributes: true
      attributes_list:
        - ETag
        - ObjectSize

返回值

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

键	描述
object_info 列表 / 元素=字典	S3 对象详细信息。 返回：当指定 bucket_name 和 object_name 时。
object_acl 复杂	对象的访问控制列表 (ACL)。 返回：当 object_details.object_acl=true 时。
grants 复杂	授权列表。 返回：始终返回
grantee 复杂	被授予权限的实体。 返回：始终返回
id 字符串	被授权人的规范用户 ID。 返回：始终返回 示例："xxxxxxxxxxxxxxxxxxx"
type 字符串	被授权人的类型。 返回：始终返回 示例："CanonicalUser"
permission 字符串	指定授予被授权人的权限。 返回：始终返回 示例："FULL CONTROL"
owner 复杂	存储桶所有者的显示 ID 和名称。 返回：始终返回
display_name 字符串	存储桶所有者的显示名称。 返回：始终返回 示例："abcd"
id 字符串	存储桶所有者的 ID。 返回：始终返回 示例："xxxxxxxxxxxxxxxxxxxxx"
object_attributes 复杂	对象属性。 返回：当 object_details.object_attributes=true 时。
checksum 复杂	对象的校验和或摘要。 返回：始终返回
checksum_crc32 字符串	对象的 base64 编码的 32 位 CRC32 校验和。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_crc32c 字符串	对象的 base64 编码的 32 位 CRC32C 校验和。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_sha1 字符串	对象的 base64 编码的 160 位 SHA-1 摘要。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_sha256 字符串	对象的 base64 编码的 256 位 SHA-256 摘要。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
etag 字符串	ETag 是 Web 服务器分配给在 URL 中找到的资源的特定版本的唯一标识符。 返回：始终返回 示例："8fa34xxxxxxxxxxxxxxxxxxxxx35c6f3b"
last_modified 字符串	对象的创建日期。 返回：始终返回 示例："2022-08-10T01:11:03+00:00"
object_parts 复杂	与分块上传相关的部件集合。 返回：始终返回
is_truncated 布尔值	指示返回的部件列表是否被截断。 返回：始终返回
max_parts 整数	响应中允许的最大部件数。 返回：始终返回
next_part_number_marker 整数	当列表被截断时，此元素指定列表中的最后一个部件 以及在后续请求中用于 PartNumberMarker 请求参数的值。 返回：始终返回
part_number_marker 整数	当前部件的标记。 返回：始终返回
total_parts_count 整数	部件总数。 返回：始终返回
object_size 整数	对象的字节大小。 返回： 总是 示例： 819
parts 复杂	与单个部件相关的元素容器。 返回：始终返回
checksum_crc32 字符串	对象的 base64 编码的 32 位 CRC32 校验和。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_crc32c 字符串	对象的 base64 编码的 32 位 CRC32C 校验和。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_sha1 字符串	对象的 base64 编码的 160 位 SHA-1 摘要。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
checksum_sha256 字符串	对象的 base64 编码的 256 位 SHA-256 摘要。 返回：如果它已与对象一起上传。 示例："xxxxxxxxxxxx"
part_number 整数	标识部件的部件编号。此值为 1 到 10,000 之间的正整数。 返回：始终返回
size 整数	上传部件的字节大小。 返回：始终返回
storage_class 字符串	对象的存储类信息。 返回：始终返回 示例： "STANDARD"
object_data 字典	包含 S3 对象元数据的字典。 返回：当bucket_name 和 object_name 已指定但 object_details 未指定时。
accept_ranges 字符串	指示是否指定了字节范围。 返回：始终返回
content_length 整数	正文（对象数据）的字节大小。 返回：始终返回
content_type 字符串	描述对象数据格式的标准 MIME 类型。 返回：始终返回
e_tag 字符串	Web 服务器分配给在 URL 中找到的资源的特定版本的唯一标识符。 返回：始终返回
last_modified 字符串	对象的创建日期。 返回：始终返回
metadata 字典	用于存储在 S3 中的对象的元数据映射。 返回：始终返回
server_side_encryption 字符串	在 Amazon S3 中存储此对象时使用的服务器端加密算法。 返回：始终返回
tag_count 整数	对象上的标签数（如有）。 返回：始终返回
object_legal_hold 复杂	对象的当前法律保留状态 返回：当 object_details.object_legal_hold=true 且在存储桶上设置了对象法律保留时。
legal_hold 复杂	指定对象的当前法律保留状态。 返回：始终返回
status 字符串	指示指定的对象是否已启用法律保留。 返回：始终返回 示例： "ON"
object_lock_configuration 复杂	存储桶的对象锁定配置。 返回：当 object_details.object_lock_configuration=true 且在存储桶上设置了对象锁定配置时。
object_lock_enabled 字符串	指示此存储桶是否启用了对象锁定配置。 返回：始终返回
rule 复杂	指定指定对象的对象锁定规则。 返回：始终返回
default_retention 复杂	要应用于放置在指定存储桶中的新对象的默认对象锁定保留模式和期限。 返回：始终返回
days 整数	要为默认保留期限指定的日期数。 返回：始终返回
mode 字符串	要应用于放置在指定存储桶中的新对象的默认对象锁定保留模式。 必须与 Days 或 Years 一起使用。 返回：始终返回
years 整数	要为默认保留期限指定的年数。 返回：始终返回
object_retention 复杂	对象的保留设置。 返回：当 object_details.object_retention=true 且在存储桶上设置了对象保留时。
retention 复杂	对象的保留设置的容器元素。 返回：始终返回
mode 字符串	指示指定对象的保留模式。 返回：始终返回
retain_until_date 字符串	此对象锁定保留将过期的时间。 返回：始终返回
object_tagging 字典	对象的标签集 返回：当 object_details.object_tagging=true 时。
s3_keys 列表 / 元素=字符串	对象键列表。 返回：仅指定 bucket_name 且未指定 object_name、object_details 时。 示例： ["prefix1/", "prefix1/key1", "prefix1/key2"]

作者

• Mandar Vijay Kulkarni (@mandar242)

集合链接

• 问题追踪器
• 代码库（源码）
• 通信