SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场aliyun-oss-skill

aliyun-oss-skill

部署与运维

查看项目

更新于 10-16 12:51

技能介绍

aliyun-oss-skill 是一个用于通过 Python 操作阿里云 OSS 的技能包，基于 alibabacloud_oss_v2 SDK 实现。它把常见的 OSS 操作封装为可独立使用的脚本与参考文档，便于在自动化流程或本地环境中调用。

一、用途 该技能面向需要通过代码管理阿里云 OSS 存储空间的场景，提供四项独立能力：列举 Bucket、创建 Bucket、设置 Bucket ACL、上传 Object。各能力相互独立，无固定调用顺序，可按需单独或组合使用。

二、目录结构 技能目录 aliyun-oss-skills/ 包含：

  • SKILL.md
  • .env.example
  • reference/：存放 API 定义（YML），含入参与返回值说明，包括 list_buckets.yml、put_bucket.yml、put_bucket_acl.yml、put_object.yml。
  • scripts/：可直接运行的示例脚本，包括 oss_util.py（凭证与 Client 构造，供脚本复用）、list_buckets.py、put_bucket.py、put_bucket_acl.py、put_object.py 以及 requirements.txt。

三、主要能力

  1. 列举 Bucket（ListBuckets / GetService）：列出当前账号下的存储空间，适用于资产盘点、按前缀或标签筛选 Bucket。常用参数包括 prefix（名称前缀过滤）、marker（分页起点）、max_keys（单次最大条数，1~1000）、resource_group_id（资源组）、tag_key/tag_value（按标签过滤）、tagging（标签列表表达式，与 tag-key/tag-value 互斥）。完整字段见 reference/list_buckets.yml。列举 Bucket 需要账号级读权限，例如策略中包含 oss:ListBuckets。
  2. 创建 Bucket（PutBucket）：在指定地域新建存储空间，适用于新环境初始化、自动化开通。常用参数包括 bucket（必填）、acl（private / public-read / public-read-write）、resource_group_id（可选）、bucket_tagging（如 k1=v1&k2=v2）。Bucket 名称须全局符合 OSS 命名规范（小写字母、数字、短划线，3~63 字符等）。创建 Bucket 需要 oss:PutBucket 等写权限；同一账号在同一地域可创建的 Bucket 数量有上限。
  3. 设置 Bucket ACL（PutBucketAcl）：对已存在的 Bucket 覆盖式设置访问权限，适用于收紧或调整 Bucket 可见性、合规整改。REST 上对应 PUT /?acl，请求头 x-oss-acl；SDK 使用 PutBucketAclRequest 的 acl 字段，必填 private、public-read、public-read-write（公共读/写请谨慎）。新 ACL 会覆盖原 ACL，并非合并。请求者需对 Bucket 拥有写入 ACL 的权限，策略中通常包含 oss:PutBucketAcl。契约说明若指定 Bucket 不存在，调用该接口会新建 Bucket；生产自动化仍建议先显式 PutBucket 创建，勿依赖该副作用。
  4. 上传 Object（PutObject）：将本地文件上传为指定 Bucket 下的 Object，适用于部署静态资源、备份文件。常用参数包括 bucket（必填）、key（Object 完整路径）、body（二进制内容，脚本从 --file 读取）、content_type（可选，脚本可按扩展名推测）、forbid_overwrite（禁止覆盖）。默认允许覆盖同名 Object；可使用 --forbid-overwrite 禁止覆盖（版本控制 Bucket 下行为以官方文档为准）。需要目标 Bucket 的写权限，例如 oss:PutObject。

四、使用方式

  1. 前置检查（必须首先执行）：调用 OSS 前须确认访问凭证已配置。检查顺序：优先检查环境变量（ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET）；若未设置，检查当前工作目录的 .env；凭证变量约定优先级为推荐 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET（与本仓库其他 Alibaba Cloud skill 一致），临时凭证可额外设置 ALIBABA_CLOUD_SECURITY_TOKEN（或 OSS_SESSION_TOKEN）；备选 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET（与 OSS Python SDK 官方示例一致），STS 时可设 OSS_SESSION_TOKEN。脚本逻辑：若已配置 ALIBABA_CLOUD_* 则使用静态凭证；否则使用 OSS_* 环境变量凭证提供者。未通过凭证检查时不应继续调用 OSS。
  2. 安装依赖：pip install -r aliyun-oss-skills/scripts/requirements.txt，或手动安装 pip install alibabacloud_oss_v2 python-dotenv。
  3. 调用示例：
  • 列举 Bucket：cd aliyun-oss-skills 后执行 python scripts/list_buckets.py --region cn-hangzhou，或 python scripts/list_buckets.py --prefix myapp- --max-keys 50。
  • 创建 Bucket：python scripts/put_bucket.py --bucket my-unique-bucket-name --region cn-hangzhou，或加 --acl private。
  • 设置 ACL：示例脚本 scripts/put_bucket_acl.py（SDK 生成骨架；运行前请在请求中设置 bucket 与 acl，或与 scripts/oss_util.py 的 create_client 方式对齐后再调用）。代码示例：from alibabacloud_oss_v2 import models as oss_models; req = oss_models.PutBucketAclRequest(bucket="examplebucket", acl="private"); resp = client.put_bucket_acl(req)。
  • 上传 Object：python scripts/put_object.py --bucket my-bucket --key path/to/object.bin --file ./local.bin --region cn-hangzhou，或 python scripts/put_object.py --bucket my-bucket --key index.html --file ./index.html --content-type text/html --region cn-hangzhou。

五、适用场景

  • 资产盘点、按前缀/标签筛选 Bucket。
  • 新环境初始化、自动化开通存储空间。
  • 收紧或调整 Bucket 可见性、合规整改。
  • 部署静态资源、备份文件。

六、限制与注意事项

  • PutBucket / PutBucketAcl / PutObject 为写操作：执行前须确认 Bucket 名称、地域、ACL 取值（public-read / public-read-write 风险高）、是否覆盖同名对象；避免对生产 Bucket 误操作。
  • REST 文档中的 query/header 名称（如 max-keys）与 Python SDK 字段名可能不同，以 alibabacloud_oss_v2.models 中 Request 类参数为准（例如 max_keys）。
  • 列举结果若 is_truncated 为 true，需用 next_marker 继续请求以翻页。
  • 错误处理：脚本对异常会打印可读信息；若为嵌套错误会尝试 unwrap 输出内层 message。若异常对象含 OpenAPI 风格 data 且带 Recommend，会一并打印。常见情况：403 AccessDenied（AK/SK 无效、RAM 策略不足或 Resource 不匹配）、404 NoSuchBucket（Bucket 不存在或地域错误）、409 BucketAlreadyExists 等（Bucket 名已被占用或冲突）。OSS Python SDK 异常类型见 alibabacloud_oss_v2.exceptions（如 ServiceError）。
  • reference/ 中的 YML 用于查阅契约；scripts/ 用于验证环境与调用链。业务与示例不符时，以官方 OSS 开发者文档与 SDK 源码为准。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。