tencentcloud-cos

Tencent Cloud COS（オブジェクトストレージ）

公式の cos-python-sdk-v5 クライアントを使って、Tencent Cloud COS のバケットとオブジェクトを管理します。

セットアップ： SecretId／SecretKey／リージョンの設定については、tencentcloud authentication を参照してください。SDK は環境変数から TENCENTCLOUD_SECRET_ID／TENCENTCLOUD_SECRET_KEY／TENCENTCLOUD_REGION を読み込みます。

CLI（推奨）

このスキルには、以下のすべての COS 操作をラップする、自己完結型の CLI scripts/cos.py が含まれています。ユーザーのリクエストがサブコマンドのいずれかにそのまま当てはまる場合は、SDK 呼び出しを独自に実装するよりも、こちらを優先してください。保守されているコードパスでは、この CLI が使用されています。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
COS="$SKILL_DIR/scripts/cos.py"; [ -f "$COS" ] || COS=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/cos.py' 2>/dev/null | head -1)
[ -f "$COS" ] || { echo "tencentcloud-cos script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

python3 $COS buckets                                  # list all buckets
python3 $COS ls mydata-1250000000 --prefix images/    # list objects
python3 $COS upload mydata-1250000000 ./report.pdf --key docs/report-2026.pdf
python3 $COS download mydata-1250000000 docs/report-2026.pdf --output ./out.pdf
python3 $COS url mydata-1250000000 docs/report-2026.pdf --expires 3600
python3 $COS du mydata-1250000000 --prefix logs/
python3 $COS cp mydata-1250000000 old/path.txt new/path.txt
python3 $COS batch-delete mydata-1250000000 --prefix temp/old/ --dry-run
python3 $COS batch-delete mydata-1250000000 --prefix temp/old/   # actually delete
python3 $COS info mydata-1250000000 docs/report-2026.pdf

すべてのフラグを確認するには、python3 $COS --help（または python3 $COS <cmd> --help）を実行してください。呼び出しごとにリージョンを指定するには、--region <region> を渡します。

使用する場面

• アカウント内のすべての COS バケットを一覧表示する
• バケット内のオブジェクトを一覧表示する（プレフィックス／区切り文字で絞り込み）
• ファイルをアップロード／ダウンロードする
• 単一のオブジェクトを削除する、またはプレフィックスを指定して一括削除する
• 署名付きダウンロード URL を生成する（プライベートバケットの共有）
• バケット／プレフィックスのストレージ使用量を計算する
• バケット内でオブジェクトをコピーする

依存関係

pip install cos-python-sdk-v5

バケット名

Tencent Cloud のバケット名は、必ず -<APPID> で終わります。例：mydata-1250000000。APPID は数値のアカウント識別子です。SDK では、バケット名を指定する箇所すべてで name-APPID の完全な形式が必要です。

クイックスタート

import os
from qcloud_cos import CosConfig, CosS3Client

config = CosConfig(
    Region=os.environ["TENCENTCLOUD_REGION"],
    SecretId=os.environ["TENCENTCLOUD_SECRET_ID"],
    SecretKey=os.environ["TENCENTCLOUD_SECRET_KEY"],
    Scheme="https",
)
client = CosS3Client(config)

ワークフロー

すべてのバケットを一覧表示する

resp = client.list_buckets()
for b in resp["Buckets"]["Bucket"]:
    print(b["Name"], b["Location"], b["CreationDate"])

バケット内のオブジェクトを一覧表示する

# Single page (max 1000 objects)
resp = client.list_objects(Bucket="mydata-1250000000", Prefix="images/", Delimiter="/")
for obj in resp.get("Contents", []):
    print(obj["Key"], int(obj["Size"]), obj["LastModified"])

# Paginate through everything
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="logs/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        print(obj["Key"])
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

ファイルをアップロードする

# Streaming upload — handles multipart / resumes / 5GB+ files transparently
client.upload_file(
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    LocalFilePath="./report.pdf",
)

ファイルをダウンロードする

client.download_file(
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    DestFilePath="./report.pdf",
)

署名付きダウンロード URL を生成する

# Default expiry 1 hour; pass Expired=86400 for 24h, etc.
url = client.get_presigned_url(
    Method="GET",
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    Expired=3600,
)
print(url)

単一のオブジェクトを削除する

client.delete_object(Bucket="mydata-1250000000", Key="uploads/old-file.txt")

プレフィックスを指定して一括削除する（ドライランによる安全確認）

# 1) Always preview first
to_delete = []
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="temp/old/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        to_delete.append({"Key": obj["Key"]})
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

print(f"Would delete {len(to_delete)} objects")
for o in to_delete[:10]:
    print("  -", o["Key"])

# 2) Confirm with the user before running this:
# resp = client.delete_objects(Bucket="mydata-1250000000", Delete={"Object": to_delete, "Quiet": "false"})
# print("Deleted:", len(resp.get("Deleted", [])))

バケット／プレフィックスのサイズを計算する（du）

total_bytes = 0
total_count = 0
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="logs/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        total_bytes += int(obj["Size"])
        total_count += 1
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

print(f"{total_count} objects, {total_bytes / 1024 / 1024:.1f} MiB")

バケット内でオブジェクトをコピーする

client.copy_object(
    Bucket="mydata-1250000000",
    Key="new/path.txt",
    CopySource={
        "Bucket": "mydata-1250000000",
        "Key": "old/path.txt",
        "Region": os.environ["TENCENTCLOUD_REGION"],
    },
)

安全に関する注意事項

• 実行前に、一括削除についてユーザーの確認を取ってください。delete_objects 呼び出しは取り消せません。COS にはデフォルトでごみ箱がありません。
• 署名付き URL はベアラートークンです。URL を知っている人は誰でも、有効期限が切れるまでオブジェクトにアクセスできます。ユーザーが明示的に長い有効期限を求めない限り、短い有効期限（1 時間）をデフォルトにしてください。
• リージョンをまたぐ操作では、CopySource にコピー元／コピー先のリージョンが必要です。リージョンが一致しない場合、NoSuchBucket が発生します。
• download_file は確認なしでダウンロード先を上書きします。ループ内でスクリプトを実行する場合は、DestFilePath を慎重に選んでください。

エラーのパターン

症状	考えられる原因
NoSuchBucket	リージョンが間違っている、またはバケット名の APPID サフィックスが間違っている
AccessDenied	サブアカウントに QcloudCOSReadOnlyAccess／QcloudCOSDataReadOnly などが付与されていない
SignatureDoesNotMatch	SecretKey の前後に空白が含まれている、またはシステム時刻が 5 分以上ずれている
RequestTimeTooSkewed	同様に、時刻がずれている

コンソールへのリンク

• COS コンソール：https://console.cloud.tencent.com/cos/bucket
• API リファレンス：https://www.tencentcloud.com/document/product/436/41330