はじめに

Google Cloud Storage（以下 GCS）を初めて触ると、多くの人が同じポイントでつまずきます。

それが「GCS のフォルダって実際何者？」
そして「list_blobs するとフォルダ名が勝手に付くの何？」という問題です。

私自身、Cloud Run から GCS の zip ファイル一覧を取得しようとした際に、01/aaa.zipという “フォルダっぽい文字列” が返ってきて「なんで？」となりました。

Consoleでは確かに「01」というフォルダの中に aaa.zip があるように見えるのに、GCS から戻ってくるのはフォルダ名込みの “文字列”。

この記事では、GCS のフォルダの正体（プレフィックス）と list_blobs の動作原理を、初心者が混乱しないよう丁寧に解説します。

Cloud Run、Cloud Functions、ETL 処理でファイルを扱う人には特に役立つはずです。

GCS にフォルダは存在しない

GCS にフォルダは存在しません。

Console 上でフォルダがあるように見えるのは、
GCS がオブジェクト名に含まれる文字列 / を利用して階層風に表示しているだけです。

例えば Console でこう見えたとしても：

01/
 └ aaa.zip

実際のオブジェクトは 01/aaa.zipという一つの文字列（キー）。

フォルダではなく、ただの名前です。

GCS が採用している「プレフィックス構造」の発想

AWS S3 と同様、GCS はオブジェクトストレージであり、
「キー文字列を並べて管理するだけ」というシンプルな構造です。

なので以下のように見えるものは、

見た目	実体
フォルダ 01 の中に aaa.zip	01/aaa.zip という 1ファイル

この理解がないと list_blobs の挙動に戸惑います。

list_blobs が返すのは “実際のオブジェクト名そのまま”

実例で見てみます。

from google.cloud import storage

client = storage.Client()
bucket = client.bucket("my-bucket")

for blob in bucket.list_blobs():
    print(blob.name)

出力例：

01/aaa.zip
01/bbb.csv
images/dog.png

フォルダのように見える部分も含めて、そのまま返るのがポイント。

つまり、list_blobs が勝手にフォルダ名を付けているわけではなく、
GCS 内部のオブジェクト名が「最初からそういう文字列」なのです。

prefix を指定するとフォルダっぽく絞り込める

フォルダ選択したい場合、バケットにフォルダ指定はできません。
代わりに prefix で絞り込みます。

blobs = bucket.list_blobs(prefix="01/")
for blob in blobs:
    print(blob.name)

出力：

01/aaa.zip
01/bbb.csv
01/sub/ccc.txt

ポイント：

"01" ではなく "01/" と書くこと
→ "01" にすると "0100/file.txt" などもヒットして事故りがち

ファイル名だけ欲しい時は basename が便利

01/aaa.zipではなくaaa.zipだけ欲しい場合、os.path.basenameを使います。

import os

for blob in bucket.list_blobs(prefix="01/"):
    filename = os.path.basename(blob.name)
    print(filename)

出力：

aaa.zip
bbb.csv
ccc.txt

Cloud Run で zip 解凍したり BigQuery ロード時にログを整理する時に超便利。

Cloud Run でよくある実戦コード例（zip 限定で一覧化）

Cloud Run ジョブ内で、特定フォルダ（prefix）にある zip だけ処理したいケース。
せいにちが実際に使っていた構造に近い形にしています。

from google.cloud import storage
import os

def list_zip_files(prefix: str):
    client = storage.Client()
    bucket = client.bucket("my-bucket")
    blobs = bucket.list_blobs(prefix=prefix)

    results = []
    for blob in blobs:
        if blob.name.endswith(".zip"):
            results.append({
                "full_path": blob.name,
                "filename": os.path.basename(blob.name),
                "size": blob.size,
                "updated": blob.updated
            })
    return results

# 実行
zip_files = list_zip_files("01/")
for f in zip_files:
    print(f)

出力例：

{
  "full_path": "01/aaa.zip",
  "filename": "aaa.zip",
  "size": 21044,
  "updated": "2025-12-10T10:01:22"
}

このように prefix で絞りつつ、オブジェクト名（full_path）と実際のファイル名（filename）を分けて扱うのがベスト。

フォルダを作ったり削除したりできるように見える理由

GCS Console では「フォルダ作成」ボタンや「フォルダ削除」操作が存在します。

しかし、実体はこうです：

フォルダ作成
→ "some-folder/" という 0バイトオブジェクトを作っているだけ

フォルダ削除
→ "some-folder/" から始まるすべてのオブジェクトを削除している

つまり、あくまで UI が“フォルダっぽく見せている”だけ。
なので、コードからフォルダ操作をしようと考える必要はありません。
常に “文字列の prefix を操作している” と考えればOK。

よくあるつまずきポイントまとめ

初心者がよく混乱するポイントをまとめると：

❌ フォルダが実体として存在する
→ 実際は / を含むオブジェクト名の区切りを UI が階層に見せているだけ

❌ list_blobs がフォルダ名を付けてくる
→ 内部オブジェクトが “はじめからそういう文字列” だから

❌ バケットにフォルダを指定して取得できる
→ prefix で絞る（"01/" など）

❌ "01" と "01/" は同じ
→ "01" は "0100" も当たる。事故りやすい。

まとめ

GCS の本質はここに凝縮されています。

GCS は階層構造を持たない、フラットなキー文字列の世界。
フォルダは存在せず、prefix で疑似的に表現しているだけ。

この理解があると、Cloud Run / Cloud Functions / BigQuery ETL のコードが一気に整理されます。
特に大量ファイル処理や prefix 分割運用をする場合、
“フォルダ” というイメージから脱却することでミスが激減します。

今後、GCS で複数ファイルを自動処理したり、
プレフィックスごとにバッチを回すような運用にも応用できます。