GEE资产管理实战：ee.data批量重命名与大小统计

我从一个实际需求说起用GEE跑了一批分类结果存成了几十个asset结果发现命名规则没定好有的叫LC_2019_v2有的叫tmp_final_new_2项目甲方过来要资料我盯着Assets面板翻了三页才找到要做的那一份。那时候我就在想如果资产能像本地文件一样批量重命名、统一检查大小、随手写个脚本管理该省多少事。后来我把GEE Python API的ee.data模块翻了个底朝天又折腾了几个星期总算是把资产管理的自动化流程跑通了。这篇就围绕ee.data这条线把资产大小查看、批量重命名、列表导出、权限梳理这些实操细节一次讲透。1. 为什么GEE资产容易失控先从Assets的结构说起GEE的Assets本质上是云端存储的地理空间对象常见的类型包括Image、ImageCollection、Table也就是FeatureCollection和Folder。Python API里访问资产列表的方式有好几种但最直接的其实是ee.data.getListAssets()它会返回指定路径下的所有子级资产。很多人习惯用ee.Image(users/xxx/xxx)去加载但那只适合已知asset ID的场景一旦你要看看某个文件夹里到底有什么就必须回到API层。我第一次管理资产时犯过一个典型错误以为ee.data.listAssets()是存在的。实际上Python API中这个方法的名称是ee.data.getListAssets而listAssets是旧版JavaScript API里的叫法。这种API名称的差异特别容易让人卡壳。另一个常见误解是Assets面板里看到的文件大小和API返回的sizeBytes字段并不是一回事后者只反映原始数据在云端存储的压缩后体积而不是你在Export.image.toAsset()任务里看到的那种估算大小。一个很实用的认知GEE的资产ID是完全路径概念users/me/folder/asset这整条路径才是唯一的。你在Assets面板里看到的文件夹嵌套本质上就是路径前缀。所以重命名操作其实是在改写路径而不单纯改一个名字字段。理解了Assets的路径机制后面看大小、改名、清理权限都会顺很多。目录结构一旦定下来建议就别频繁改尤其是被别人通过users/xxx/...路径共享出来的folder你改名前一定要拿到owner授权否则API会直接报PERMISSION_DENIED。2. 用ee.data拿到资产列表和真实大小2.1 一次性拉取完整资产树ee.data.getListAssets需要两个关键参数parent和options。parent就是你要列目录的路径比如projects/your-project/assets/xxx或users/xxx/xxx。options里可以传的参数包括limit、offset、types等。下面是官方推荐的写法我自己加了点容错import ee import json ee.Initialize() parent users/yourusername/yourfolder options { limit: 1000, # 每次最多返回的条数 types: IMAGE,IMAGE_COLLECTION,TABLE,FOLDER # 可选的类型过滤 } # getListAssets返回的是一个List-like容器可以直接迭代 assets ee.data.getListAssets({parent: parent, options: options}) print(type(assets)) # class ee.data.ApiList这里有个坑返回的ApiList对象虽然能直接for循环和切片但它本身不是Python list。如果你拿去len()或assets[0][id]还正常但想当然用assets[:10]在旧版本API里会报错。我一般习惯先转成普通列表asset_list list(assets)每个资产item的dict字段大致如下字段含义实际用途id资产完整路径后续所有update操作的主键type资产类型过滤用sizeBytes数据大小字节统计磁盘占用creationTime创建时间毫秒时间戳时间维度管理properties属性的dict含系统属性和自定义属性写脚本做标记sizeBytes并不是所有资产类型都有。比如FOLDER就没有因为文件夹本身不存储数据需要递归求和子项。这点我一开始没意识到以为拿到list就万事大吉结果统计出来的总大小比Assets面板少了好几个T因为漏了子文件夹里的内容。2.2 自动汇总每个文件夹的大小受限于API一次最多返回几百条的限制如果你的folder里资产特别多limit需要合理设置并且注意offset分页。我写过一个小函数可以递归遍历所有子文件夹并返回一个id-sizeBytes的映射def walk_assets(parent): result {} opts {limit: 1000} while True: batch list(ee.data.getListAssets({parent: parent, options: opts})) for item in batch: asset_id item[id] asset_type item.get(type) result[asset_id] item if asset_type FOLDER: # 递归 sub walk_assets(asset_id) result.update(sub) if len(batch) opts[limit]: break opts[offset] opts.get(offset, 0) len(batch) return result注意一个细节getListAssets返回的数据大小单位是字节但实际项目里大家更熟悉GB。转成GB时我习惯保留两位小数并且在脚本输出时对齐名称列方便一眼看出哪个资产是胖子。def human_readable_size(num_bytes): if not num_bytes: return 0 B size float(num_bytes) for unit in [B, KB, MB, GB, TB]: if size 1024.0: return f{size:.2f} {unit} size / 1024.0 return f{size:.2f} PB经验之谈只看sizeBytes有时候会让人误判。比如一个ImageCollectionAPI返回的sizeBytes可能是0因为集合本身只是索引真正的大小在集合内的每张Image上。要准确统计必须把ImageCollection继续拆开对集合下的每个image调getListAssets或者直接读集合的元数据统计count和每个tile的大小。在我的资产管理脚本里最终输出类似这样的报告资产清单users/myuser/LandCover ------------------------------------------ IMAGE LC_2019_v2 12.34 GB IMAGE LC_2020_raw 15.67 GB FOLDER training_data 0 B (内含64项) TABLE validation_pts 45.2 MB这一部搞定后清理逻辑就简单了——哪些是历史遗留的废弃中间产物直接按大小和创建时间排序就能列出来。3. 批量重命名资产的完整脚本从需求到实现3.1 先确认GEE能做什么在动手写重命名脚本前我心里是有几个问题的GEE Python API有没有renameAsset如果没有官方推荐的替代思路是什么答案是没有直接的rename接口。资产重命名的本质是复制一个新的assetid然后删除旧的。GEE并没有提供单步操作的API你只能用ee.data.copyAsset在较新的API版本中通过ee.data.newCopyAsset或ee.data.copyAsset方法把原资产复制到一个新路径。验证复制结果是否完整。用ee.data.deleteAsset把原路径删掉。不过这里有个很关键的坑复制大assets非常耗时而且会占用大量云端配额。如果你只是想把命名规范化不一定非要复制整个数据。在Assets管理界面你会发现重命名其实也是同样的套路——Google会先复制再删除但用户感觉像是重命名。既然用了API就要把这个机制理解清楚。老版本sumbitCopy早就不推荐了。现在推荐的方法名称在不同版本有差异我在自己的环境里验证过ee.data.copyAsset是稳定可用的。具体用法source_path users/me/old_folder/LC_2019_v2 dest_path users/me/new_folder/LC2019_final ee.data.copyAsset(source_path, dest_path)3.2 安全重命名的四个阶段我不建议直接对生产库里的资产做复制删除。正确流程应该是阶段一检查源路径存在性和类型def asset_exists(asset_id): try: info ee.data.getAsset(asset_id) return True except ee.EEException: return False通过getAsset能拿到完整信息避免在copy时才发现路径写错了。阶段二检查目标路径冲突如果目标路径已经存在资产复制会报错。所以写脚本前先枚举目标文件夹的所有子项构造一个冲突列表def check_dest_conflict(dest_parent, dest_name): children list(ee.data.getListAssets({parent: dest_parent})) for child in children: if child[id].endswith(/ dest_name): return True return False阶段三执行复制并校验复制并不是瞬间完成的。copyAsset返回的是异步任务ID你需要等待任务完成。建议用ee.data.getOperationStatus轮询任务状态def copy_and_wait(source, dest): task_id ee.data.copyAsset(source, dest) while True: status ee.data.getOperationStatus(task_id) # 注意不同版本可能叫getTaskStatus state status.get(state) if state COMPLETED: print(f复制完成: {source} - {dest}) break elif state in (FAILED, CANCELLED): raise RuntimeError(f复制失败: {status}) time.sleep(3)注意copyAsset返回的task id与导出任务的id机制类似。高并发任务时GEE有每秒任务数限制建议加个time.sleep(0.5)或限制并发数。阶段四删除源资产校验通过后才能删除旧路径。ee.data.deleteAsset(source)我把这四个阶段封装成了一个模块asset_renamer.py提供rename_asset函数def rename_asset(source_path, new_path, safe_modeTrue, dry_runFalse): if dry_run: print(f[DRY RUN] {source_path} - {new_path}) return if not asset_exists(source_path): raise ValueError(f源资产不存在: {source_path}) if asset_exists(new_path): raise ValueError(f目标路径已存在: {new_path}) if not safe_mode: print(非安全模式将直接复制不做类型检查) copy_and_wait(source_path, new_path) # 复制完成后确认目标资产可读取再删除 assert asset_exists(new_path), 复制完成但目标不存在异常 ee.data.deleteAsset(source_path) print(f重命名完成: {source_path} - {new_path})安全模式下上面这个函数已经覆盖了常见风险。但有一个坑值得专门提如果源资产是一个巨大的ImageCollection复制会非常慢甚至出现半个小时后任务仍然在跑的情况。这种场景下比起硬等更好的做法是直接在代码层面构建一个新的ImageCollection把元数据转移然后对每个子Image异步复制。但那样脚本复杂度会高不少。3.3 批量场景正则表达式配合csv配置实际使用中我通常不会手写一个个source - dest映射而是把映射关系写进CSV脚本循环处理。尤其是资产重命名涉及几十上百个条目的情况CSV配置方便审计和回滚。source,dest users/me/old/tmp_LC2019,users/me/final/LC2019 users/me/old/ndvi_test_area,users/me/products/NDVI_2023然后用一个小函数读csv并批量执行import csv def rename_from_csv(csv_file): with open(csv_file, newline, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: src row[source].strip() dst row[dest].strip() if src and dst: try: rename_asset(src, dst) except Exception as e: print(f!! 失败: {src} - {dst}, 错误: {e}) continue这个批量脚本跑起来屏幕上会实时打印进度数据。有一次跑完200多条资产后我收到一个异常发现某条源路径其实是共享自其他人的folder我没有写权限。脚本里加了异常捕获所以没中断后续我在权限上做了单独处理。这类问题下面单开一节讲。4. 重命名之外的资产管理陷阱4.1 权限与共享资产不能随便动GEE资产权限体系是三级的owner、writer、reader。你只有是资产的owner才能执行复制和删除操作。对于别人共享给你、只有writer权限的资产复制可能可以取决于共享设定但删除一定不行。所以批量重命名前先确认你对着的每个资产是不是属于users/你本人的路径。更麻烦的是有时你用ee.data.getAsset判断不了owner因为返回的metadata里不一定直接包含所有者字段。一个取巧的办法看asset的ID开头是不是你自己的用户目录或项目路径。如果确实需要管理共享资产建议直接联系对方grantwriter或owner权限不要搞复制一份到自己的users路径下用新旧并用的方案——这会产生数据冗余和后续混乱。4.2 资产大小统计的准确性分析我踩过的另一个大坑是把sizeBytes拿来当真要导出的体积用。实际上GEE存储的资产是专门格式化的压缩数据和你用Export.image.toDrive导出成GeoTIFF后的体积并不等同。压缩格式下分类栅格可能只有几百MB导出后却有好几GB。做成本估算和配额管理时两者都要注意。通常我先用sizeBytes做粗略排序找出排名前10的大资产再单独对这几个资产做getAsset看细分项。表格如下资产IDsizeBytes导出预估用途建议LC_2019_v212.34GB25GB分类结果保留temp_analysis20.1GB40GB临时中间结果删除NDVI_2020_old8.2GB16GB旧版本重命名归档这种清单整理出来跟项目组开资产清理会就非常有效率。4.3 使用ee.data.listFeatures等边界情况对于Table类型的资产如果你想了解表内有多少条记录getAsset返回的信息不一定包含featureCount。可以用ee.FeatureCollection(asset).size().getInfo()获取。但是getInfo()在服务器端运行对于超大表几百万要素可能响应很慢。推荐用asset.size元数据中的features字段或者在导出任务里看输出行数。普通管理场景下不必常查feature count。5. 脚本落地一个包含建目录、统计、重命名的通用工具前面讲了那么多零散的API组合这里我给出一个完整的、可以直接用的工具脚本骨架。包括初始化GEE、列出资产树、统计大小、安全重命名四个功能。你根据自己的环境填上用户名和路径后就能跑。#!/usr/bin/env python3 GEE资产管理小工具列表、大小、重命名。 import time import argparse import ee # 初始化 ee.Initialize() def human_readable_size(size): if size is None: return N/A size float(size) for unit in [B, KB, MB, GB, TB]: if size 1024.0: return f{size:.2f} {unit} size / 1024.0 return f{size:.2f} PB def list_assets(parent): 列出父路径下的直接子资产。 items list(ee.data.getListAssets({parent: parent})) if not items: print(无资产。) for item in items: size item.get(sizeBytes) print(f{item[type]:12} {item[id]:60} {human_readable_size(size)}) return items def count_folder_size(folder_id, depth0): 递归统计文件夹大小。 total 0 items list(ee.data.getListAssets({parent: folder_id})) for item in items: if item[type] FOLDER: total count_folder_size(item[id], depth 1) else: total item.get(sizeBytes, 0) or 0 return total def rename_asset(src, dst, safeTrue): if not ee.data.getAsset(src): print(f源不存在: {src}) return False try: ee.data.getAsset(dst) print(f目标已存在: {dst}) return False except Exception: pass # 目标不存在可以继续 print(f开始复制: {src} - {dst}) task_id ee.data.copyAsset(src, dst) while True: time.sleep(3) status ee.data.getOperationStatus(task_id) state status.get(state) if state COMPLETED: print(复制完成) break elif state in (FAILED, CANCELLED): print(f复制失败: {status}) return False # 复制成功后删旧 ee.data.deleteAsset(src) print(删除旧资产完成) return True if __name__ __main__: parser argparse.ArgumentParser(descriptionGEE资产管理工具) sub parser.add_subparsers(destcmd) p_list sub.add_parser(list, help列出资产) p_list.add_argument(parent, help父路径) p_rename sub.add_parser(rename, help重命名资产) p_rename.add_argument(src, help原始路径) p_rename.add_argument(dst, help新路径) p_rename.add_argument(--force, actionstore_true, help覆盖目标存在检查) p_size sub.add_parser(size, help统计文件夹大小) p_size.add_argument(folder, help文件夹路径) args parser.parse_args() if args.cmd list: list_assets(args.parent) elif args.cmd rename: rename_asset(args.src, args.dst, safenot args.force) elif args.cmd size: print(f总大小: {human_readable_size(count_folder_size(args.folder))}) else: parser.print_help()直接跑之前注意几点脚本里的ee.data.copyAsset在高版本比如0.1.375已经稳定存在如果你的环境是用老教程装的0.1.230可能会找不到。解决方法很简单pip install --upgrade google-earth-engine升级到新版。6. 与热词相关的扩展思路最近搜GEE相关关键词时很多人在问GEE Python API 调用讯飞星火api这类组合场景其实就是两件事GEE负责地理数据处理星火API负责大模型交互。把它延伸到资产管理上可以实现一个很有想象力的功能用自然语言对话生成重命名规则。比如你采集了当前资产列表把asset_id、type、sizeBytes、creationTime拼成一个prompt让大模型输出建议的新的规范化命名再做一个确认环节把结果映射到rename_asset批量执行。我自己跑过一个demo效果还可以但生成结果必须人工审核——毕竟大模型对地理空间命名规范的理解还停留在看起来整齐上而不是符合任务语义。还有一个热词是gee ndwi用NDWI做水体提取和资产管理的结合点在于很多用户会产出几十景NDWI中间结果命名往往是NDWI_20200101这种基于时间序列的。时间久了没人记得每个asset的生产参数云掩膜阈值、波段选择等所以好的习惯是在properties里写自定义属性比如{source_collection: Landsat8/OLI, extraction_method: Otsu, cloud_thresh: 0.2}。这样即使资产ID重命名了属性还在追溯信息不会丢失。在Asset管理脚本里加一行输出properties的代码就能看到。另一个有意思的经验是把资产重命名做成周期性的例行清理。数据生产流程跑完Export后自动生成asset并记录到日志每周末跑一次脚本把tmp_前缀且创建时间超过30天的asset列出来按大小排序再确认删除。这套机制我已经用了好几个月GEE的Assets面板清爽多了配额压力也小了不少。7. 关键踩坑复盘与自查清单这两年用过不少GEE资产管理脚本有些坑属于老手也会翻车的类型。我给自己列了个自查清单每次跑批处理前过一遍检查项原因目标路径是否已有同名资产否则copydest exists报错是否包含子文件夹必须递归处理是否有跨项目复制需求跨项目时可能需要额外权限是否考虑了配额限制同时复制大量大asset会打爆每日配额是否记录了操作日志没有日志错了都不知道改了什么是否通知了协作成员其他人可能引用了旧路径在跨项目复制时解决方案不是直接用ee.data.copyAsset因为复制到另一个project的asset路径需要确保目标project有足够配额并且你的账号是目标project的成员。在云端这类复制不能简单一级调用需要先确认目标project必要时用ee.data.createAsset创建根目录再复制。还有一次我以为ee.data.getListAssets返回的空列表表示没有资产其实是parent写错了如果你把父路径最后少一个斜杠它也可能报错或不匹配。比较稳妥的做法是先用Assets UI网页确认路径再写进脚本里。路径这种东西肉眼很难看出错。最后提示Python API的版本差异真的会绊人。不同版本的ee.data.getOperationStatus返回值里的state字段可能叫status或STATE写轮询逻辑时最好先打印出status看看键名别硬编码。这也是排查任务状态时最耗时间的地方。回到开头说的问题——几十个命名混乱的asset。我用这套脚本花了不到十分钟跑完所有重命名并把一个废弃的tmp_前缀文件夹整个删了释放了将近50GB配额。后面同事再问我要数据我可以直接甩给他一份自动生成的资产清单表格。这就是把资产管理从手工点击面板升级成脚本驱动工作流最大的好处。如果你也被GEE资产搞得焦头烂额不妨从上面这段代码开始先跑一个list看看你手头到底有多少资产再动手规划重命名。真跑起来你只会后悔没有早点写这个脚本。