GEE Assets 批量删除与复制实战指南

资产目录越堆越乱这件事几乎每个用 Google Earth Engine 做过几个项目的人都躲不过。最初的几个月图省事导入的影像随手丢在根目录命名全靠手打Collection 和 Image 混在一起等到项目交接或者要清理额度的时候才发现面对着一个几百上千条记录的 Assets 列表无从下手——点一条删一条太慢写脚本批量处理又怕误删而且到底该用 Code Editor 里的 JavaScript 还是本地 Python 脚本两边的 API 名字长得像但细节完全不同。这篇就是把我在 Google Earth Engine 里删除和复制指定 ASSETS 中文件信息的整套做法摊开讲JavaScript 版本适合在浏览器里快速验证和少量操作Python 版本适合挂在本地做批量任务和清单驱动的大规模清理涵盖单个资产删除、文件夹与集合的递归处理、跨项目复制、批量清单驱动流程以及那些文档里不写但实际会卡住你的坑。刚接触 GEE 不久、只会点鼠标导入导出的同学能照着跑通已经在做数据治理、需要定期整理资产目录的老手也能从批量脚本和排查表里直接抄作业。1. Assets 目录结构与管理边界先摸清楚动手删之前得先搞清楚你操作的到底是什么。Google Earth Engine 的 Assets 不是一个平铺的文件列表而是一棵有类型、有父子关系的树。树上的每个节点都有明确的类型标签删除和复制在不同类型上的行为差异极大。跳过这一步直接写脚本十有八九会得到意料之外的结果。1.1 Asset ID 的三段式结构与类型标签一个完整的资产 ID 长这样projects/your-cloud-project/assets/folder_a/sub_b/my_image_2024。拆开看是三段projects/后面跟云项目标识中间固定是assets后面才是你在 Code Editor 里看到的人类可读路径。老账号还会见到users/your_account/xxx这种写法那是历史遗留的别名前缀实际指向同一个存储位置两种写法在新版 API 里都能用但混着写容易在脚本里出对不上的问题建议统一成projects/...的形式。真正决定操作行为的是资产类型。用一次ee.data.getAsset()就能拿到类型字段常见取值有四种FOLDER纯目录只能装东西、IMAGE单张影像、IMAGE_COLLECTION影像集合下面挂着若干 items、TABLE矢量/表格。这四类在删除时的语义完全不同FOLDER 和 IMAGE_COLLECTION 是容器删除容器意味着连里面的东西一起没了IMAGE 和 TABLE 是叶子删了就是删了。很多人第一次踩坑就踩在这以为删集合只是删个空壳结果底下几百张影像一起消失。1.2 为什么删除和复制是两套逻辑这两件事听起来对称实际上在 GEE 里根本不是一回事。删除是一个纯粹基于 ID 的操作你给出 ID服务端校验权限、校验是否存在然后执行没有中间状态也不产生新对象。复制则要读取源资产的全部元数据和底层数据引用再在目标位置重新登记一遍涉及数据搬迁、属性继承、权限继承甚至可能触发配额计算。这个不对称直接决定了脚本设计的差异。删除脚本的核心是清单要准你要做的是把待删 ID 列全、列对、再核一遍执行环节反而简单。复制脚本的核心是目标要对源 ID 和目标 ID 的映射关系必须在执行前全部算清楚因为复制过程中一旦中断你会得到一个半成品——源资产还在目标资产也可能存在一部分清理起来比重来一遍更麻烦。我在实际项目里养成的习惯是删除脚本永远配一个 dry-run 模式先把将要删除的清单打印出来人工扫一眼再执行复制脚本永远先在测试目录跑一个样本确认目标结构、权限、属性都没问题再放开跑全量。听起来笨但省下的返工时间远超这点开销。1.3 权限与不可逆性动手前的三条底线底线一删除操作不可恢复。GEE 没有回收站没有软删除没有七天之内可还原。ee.data.deleteAsset一旦返回成功那个 ID 就真的不存在了。所以任何删除动作前务必确认你手里有原始数据来源或者可重建的流程尤其是从本地导入的影像源文件丢了就真没了。底线二权限分三层。你需要在云项目层面有编辑权限在目标资产上具备写入权限在父目录上有管理能力。三者缺一表现出的报错信息差别很大有的是Permission denied有的是Not found对着报错猜半天不如提前用ee.data.getAsset()探一下能不能读到读不到大概率也写不了。底线三写操作有速率限制。GEE 对deleteAsset、copyAsset这类写调用是有配额约束的短时间内高频调用会被限流报 429 或者超时。批量脚本必须带节流和重试不能裸奔循环。这一点在 Code Editor 里尤其明显因为浏览器侧还有执行时长限制几百条以上的清理任务老实写 Python 脚本挂本地跑。2. 环境准备JS 与 Python 双线开工JavaScript 和 Python 两个版本不是二选一的替代关系而是各有各的舒适区。我的用法是探索阶段、单条验证、临时救火走 Code Editor正式批量任务、需要日志和断点续跑的走本地 Python。下面把两条线的准备工作都说清楚。2.1 Code Editor 侧的零配置路径JavaScript 版本几乎不需要准备。打开 Code Editor确认右上角的云项目已经切换到你要操作的那个项目然后直接在 Console 里敲代码就行。不需要写ee.Initialize()因为编辑器环境会自动完成认证和初始化。这是它最大的优势——想试什么当场就试。有一点要特别注意Code Editor 里的脚本运行在浏览器发起的请求上下文里返回的是异步结果。如果你直接在 Console 里敲ee.data.deleteAsset(xxx)可能会看到undefined而不是成功提示这不算失败只是调用发出去了、回调还没回来。稳妥的写法是带上回调把结果打出来ee.data.deleteAsset( projects/your-cloud-project/assets/temp/old_image_01, function (result, error) { if (error) { console.error(删除失败:, error); } else { console.log(删除成功:, result); } } );带回调的写法虽然啰嗦但它是唯一能让你确认到底成没成的方式。不带回调的调用在遇到权限错误时会静默失败你以为删掉了回头一看还在。2.2 本地 Python 环境与认证Python 侧需要一个能跑earthengine-api的环境。我的习惯是建独立虚拟环境避免和本机其他地理相关的包打架毕竟geopandas、rasterio这些依赖经常互相拉扯版本。python -m venv gee_env source gee_env/bin/activate # Windows 用 gee_env\Scripts\activate pip install earthengine-api装完之后走一次认证。earthengine authenticate会拉起浏览器登录你常用的账号拿到凭据后写到本地配置目录。这一步只需做一次之后所有脚本共享这份凭据。认证时有一点要留意如果你有多个可用账号务必确认浏览器当前登录的是对目标资产有写权限的那个切换账号后需要重新跑一次认证旧凭据不会自动失效容易出现我明明有权限的假象。脚本开头固定三行import ee ee.Initialize(projectyour-cloud-project)project参数在新版本里建议显式指定。不指定时 API 会尝试从凭据里推断推断失败或者推断到旧项目上就会出现资产存在但找不到的诡异情况。显式写死项目标识是让脚本可复现的最省事做法。2.3 一个必须提前确认的账号属性无论 JS 还是 Python都要确认一件事你当前身份对目标父目录是否具备写权限。快速验证方法是列一次父目录的资产parent projects/your-cloud-project/assets/temp listing ee.data.listAssets({parent: parent, pageSize: 10}) for a in listing.get(assets, []): print(a[type], a[name])能正常列出内容说明读权限没问题然后随手复制一个小资产到同目录再删掉能跑通就说明写权限也没问题。这套读一遍、写一遍、删一遍的预检花不到一分钟但能挡掉后面 80% 的权限类报错。我见过太多次有人写了半天批量脚本跑起来第一条就Permission denied回头发现是云项目的 IAM 角色没配对而这个问题本来一步就能提前发现。3. 删除指定 Assets从单文件到批量清单删除本身不难难的是删对。这一节从单条删起讲到递归删除、批量删除最后给一个必须加的安全机制。3.1 单个资产删除的最小闭环JavaScript 版本的核心就一个函数ee.data.deleteAsset(assetId, callback)。Python 版本把驼峰换成下划线参数变成一个ee.data.delete_asset(asset_id)。Python 侧是同步调用成功返回空失败抛异常比 JS 的回调好用得多。Python 侧我会包一层把异常捕获和日志处理掉这样批量循环时不会因为一条失败就整体崩掉import ee import time def delete_one(asset_id, retries3): for attempt in range(retries): try: ee.data.delete_asset(asset_id) print(f[OK] {asset_id}) return True except Exception as exc: msg str(exc) if not found in msg.lower(): print(f[SKIP] {asset_id} 不存在) return False if attempt retries - 1: print(f[FAIL] {asset_id} - {msg}) return False wait 2 ** attempt print(f[RETRY {attempt1}] {asset_id} 等待 {wait}s) time.sleep(wait)这段代码里有两个设计一是不存在单独识别并跳过不算失败因为批量清单里混着已经被手动删掉的条目太正常了二是指数退避重试应对限流和瞬时网络抖动。这两点看着琐碎但批量跑几百条时能把失败率从两位数压到接近零。3.2 递归删除文件夹与集合的真实行为这是最容易出事的地方。对FOLDER类型的资产调用删除会把文件夹及其下所有内容一并删掉对IMAGE_COLLECTION调用删除同理集合和它下面的所有 items 一起消失。官方 API 里还有ee.data.deleteCollection(collectionId)这个更早的函数Python 侧叫ee.data.delete_collection新版基本统一到delete_asset上了两者行为接近用哪个都行但别在同一套脚本里混着用容易在异常处理上出现不一致。我的做法是删除任何容器类型之前强制先跑一次递归清单打印。def list_children(parent_id): 递归列出 parent 下所有子资产 ID result [] page_token None while True: params {parent: parent_id, pageSize: 1000} if page_token: params[pageToken] page_token resp ee.data.listAssets(params) for a in resp.get(assets, []): result.append(a[name]) if a[type] in (FOLDER, IMAGE_COLLECTION): result.extend(list_children(a[name])) page_token resp.get(nextPageToken) if not page_token: break return result这里必须提分页。listAssets单次返回是有上限的默认 1000 条超出部分靠nextPageToken翻页。不处理分页的脚本在大目录上会看起来跑完了实际只处理了第一批。我最早写的清理脚本就栽在这上面打印出来的清单只有六十多条对着目录一数实际有三百多差点漏删导致后续重建时 ID 冲突。判断方法很简单翻页拿到nextPageToken就继续直到返回空。递归本身也有风险——深度太深可能超时资产特别多时内存会涨。稳妥方案是用显式栈代替递归def walk_assets(root_id): stack, out [root_id], [] while stack: cur stack.pop() params {parent: cur, pageSize: 1000} while True: resp ee.data.listAssets(params) for a in resp.get(assets, []): out.append(a) if a[type] in (FOLDER, IMAGE_COLLECTION): stack.append(a[name]) token resp.get(nextPageToken) if not token: break params[pageToken] token return out3.3 批量删除分页、限速与失败重试批量删除的标准流程是四步读清单、过滤、预演、执行。清单可以来自listAssets的遍历结果也可以来自你手写的文本文件一行一个 ID。后者在我知道要删哪几个的场景下更可控我通常把待删清单写进一个to_delete.txt脚本读文件、去重、去空行然后跑。过滤环节是防止误删的关键。常见过滤条件有三类过滤维度判断依据典型用途类型asset[type]只删 IMAGE保留所有 TABLE时间资产属性里的system:time_start清理某时间点之前的旧版本命名ID 里的关键词或前缀清理_tmp、_test结尾的临时资产限速方面我的经验值是两个删除请求之间间隔 0.5 到 1 秒。纯粹串行加time.sleep(1)是最稳的做法看起来慢但一条 500 条的任务也就八分多钟比被限流后反复重试快得多。如果你非要用并发务必把并发数压到 3 到 5并且给每条任务独立的重试逻辑否则一个 429 会连带整批失败。还有一个实操细节删除过程中如果脚本崩溃你需要知道删到哪了。所以每删一条就写一行日志到文件格式带上时间戳和结果状态。恢复时先读日志跳过已成功的从断点继续。这套机制听着繁琐但它让整个流程变成可中断、可恢复的尤其适合资产量大、需要分几个晚上跑完的场景。3.4 一个安全的预演机制我把 dry-run 做成了脚本的默认行为要真正执行必须显式加参数import sys DRY_RUN --execute not in sys.argv for aid in targets: if DRY_RUN: print(f[DRY] 将删除 {aid}) else: delete_one(aid)这个小设计救过我一次。当时我按关键词2023筛清单本意是清理某批临时影像结果清单里混进了一条正式项目的数据因为它恰好也叫..._v2023_final。dry-run 打印出来时我扫了一眼觉得数量不对回头查才发现。要是直接执行那条数据就是永久丢失。预演阶段还应该做两件事一是统计将要删除的资产总大小通过ee.data.getAsset拿sizeBytes字段累加心里有个数删掉的东西多不多二是把清单备份到本地文件名带日期万一要追溯上个月删了什么还有据可查。4. 复制指定 Assets跨项目、跨目录的迁移复制比删除复杂得多。删除是单点操作复制是读源、写目标的组合动作中间任何一步出问题都会留下不一致状态。这一节把能复制的、不能复制的、怎么复制、复制不了怎么办都说清楚。4.1 copyAsset 能复制什么、不能复制什么JavaScript 侧的函数签名是ee.data.copyAsset(sourceId, destinationId, overwrite, callback)Python 侧是ee.data.copy_asset(source_id, destination_id, overwriteFalse)。参数很直白源 ID、目标 ID、是否允许覆盖已存在的目标。能干净复制的是IMAGE和TABLE。单张影像复制过去几何、波段、属性、时间戳都会完整保留表格复制同理要素和属性都在。这两种是复制的舒适区日常迁移基本靠它们。IMAGE_COLLECTION就麻烦了。集合本身是一个容器对象它的 items 是独立登记的资产。复制集合时容器层面的元数据可以复制过去但底下的 items 是否跟着走、复制后 items 在新集合下能否正常索引不同 API 版本表现不完全一致。我实测过几次结果不稳定有时候新集合是空的有时候能带过去一部分。所以我的结论很明确生产环境不要指望 copy 一整个 ImageCollection走重建路线。至于FOLDER根本不存在复制文件夹这回事。API 没有这个能力你要做的是遍历文件夹下的每个叶子资产逐个复制到目标目录的对应路径目录结构得自己在脚本里拼。4.2 单资产复制的参数细节先看最小可用版本ee.data.copy_asset( projects/your-cloud-project/assets/raw/scene_001, projects/your-cloud-project/assets/archive/scene_001, overwriteFalse )overwriteFalse是默认值也是我强烈建议保持的值。设成True时如果目标 ID 已存在会用源覆盖目标——注意方向是源覆盖目标不是跳过。在批量场景下这个语义很危险一旦源和目标搞反会把好数据覆盖成旧数据。我宁可让脚本在冲突时报错停下来人工确认后再单独处理那几条。跨项目复制也是同一套写法只要目标路径写的是另一个项目的标识ee.data.copy_asset( projects/project-a/assets/dataset_x, projects/project-b/assets/migrated/dataset_x, overwriteFalse )前提是你对两个项目都有相应权限且目标目录已经存在。这一点经常被忽略copyAsset不会自动创建中间目录。目标路径里的migrated如果不存在复制会失败。所以批量迁移前先把目录结构建好def ensure_folder(path): try: ee.data.getAsset(path) return except Exception: ee.data.createFolder(path)ee.data.createFolder(path)也是幂等的友好写法但为了兼容已有目录的情况先 get 再 create 更稳。4.3 批量复制的清单驱动写法批量复制我一律用映射表驱动而不是在脚本里现场拼路径。做法是准备一个 CSV两列source和destination。脚本读表、逐行执行。好处是映射关系一目了然可以在表格软件里批量编辑、去重、做审核也比在代码里写字符串拼接安全得多。import csv import ee import time ee.Initialize(projectyour-cloud-project) def copy_one(src, dst, overwriteFalse, retries3): for attempt in range(retries): try: ee.data.copy_asset(src, dst, overwrite) print(f[OK] {src} - {dst}) return True except Exception as exc: msg str(exc) if already exists in msg.lower(): print(f[CONFLICT] {dst} 已存在跳过) return False if attempt retries - 1: print(f[FAIL] {src} - {dst} : {msg}) return False time.sleep(2 ** attempt) with open(copy_plan.csv, newline, encodingutf-8) as f: for row in csv.DictReader(f): copy_one(row[source].strip(), row[destination].strip()) time.sleep(0.5)这里的 0.5 秒间隔和删除脚本同理防限流。CSV 里的路径我要求写全不允许用变量拼就是为了避免某一行写错了但看着像对的这种隐性错误。批量复制的顺序也有讲究。如果目标目录下有依赖关系比如后续脚本会按目录扫数据建议按目标路径排序后再执行这样日志读起来是分组的出问题时容易定位是哪个目录出的岔子。4.4 大集合的替代方案重建而非复制对于IMAGE_COLLECTION可靠路线是重建。核心思路是从源集合里读出所有 image逐个导出到目标集合最后目标集合自然形成。src ee.ImageCollection(projects/your-cloud-project/assets/raw/col_2024) dst_id projects/your-cloud-project/assets/archive/col_2024 images src.toList(src.size()) count src.size().getInfo() print(f共 {count} 张影像待迁移) for i in range(count): img ee.Image(images.get(i)) task ee.batch.Export.image.toAsset( imageimg, descriptionfmigrate_{i:04d}, assetIdf{dst_id}/{img.id().getInfo()}, scaleimg.projection().nominalScale().getInfo(), maxPixels1e13 ) task.start() print(f[TASK] {i} - {task.id})几点说明。第一assetId用了集合ID/影像ID的拼接形式影像 ID 本身必须唯一如果源集合里有重名影像需要自己加序号后缀。第二导出任务走的是批处理队列不是同步接口task.start()只是提交实际执行时间可能是几分钟到几小时用task.status()轮询。第三scale用原影像的 nominal scale 能最大程度保真但如果原影像是多分辨率混合的得按实际情况取统一值。这条路慢但它的好处是每个影像都是独立任务任何一个失败不影响其他重跑只需补失败的那几个。而且导出完成后目标集合是干净的、结构完整的不会有复制了但索引不到的残留问题。还有一个取巧做法值得提如果只是想在另一个项目里看到同一批数据不涉及权限隔离和独立管理直接用ee.ImageCollection(源ID)引用就行根本不需要复制。复制的场景通常是权限隔离A 项目的人不能访问 B 项目或者要独立演进两边后续各自加数据。先想清楚属于哪种能省掉大量无意义的搬迁工作。5. 常见问题与排查速查表脚本跑不通的时候报错信息往往语焉不详。下面这张表是我这几年攒下来的对照表覆盖了实际遇到的绝大多数情况。5.1 报错信息对照表报错关键词大概率原因处理方式Permission denied当前账号对目标无写权限检查云项目角色确认账号切换正确Not found资产 ID 写错或已被删除用getAsset逐个确认 ID 拼写already exists目标 ID 已存在且未允许覆盖改名、换目录或人工确认后覆盖Too many requests/429触发写操作限流加大间隔到 1s加重试退避Invalid argumentID 格式不合法缺projects/前缀统一路径拼接函数避免手打Deadline exceeded单次操作涉及资产过大或深度过深拆分任务改用导出批处理User memory limit exceeded客户端侧计算量超限减少getInfo调用改服务端表达式表里最后两条值得单独说。Deadline exceeded在 Code Editor 里特别频繁因为它有硬性的执行时长限制处理大目录的递归遍历时容易被掐断。解决办法是把任务挪到 Python 本地跑本地没有这个约束。User memory limit exceeded通常是因为在客户端遍历了太多元素比如对几千条资产逐个getInfo()每次调用都是一次完整往返。优化方向是尽量用服务端表达式批量处理实在要逐条处理就分页、分批。5.2 三个容易踩的隐性坑第一个坑资产 ID 的大小写和空格。GEE 的 ID 是大小写敏感的Scene_001和scene_001是两个不同的资产。从表格里复制路径时经常会带上首尾空格不加.strip()就会得到Invalid argument而且报错信息不会告诉你是空格问题。我现在的习惯是读入任何 ID 后立刻 strip 并校验前缀。第二个坑删除集合后 ID 不能马上复用。删掉一个 ImageCollection 后如果立刻在原位置创建同名集合偶发会出现已存在的报错。这是服务端状态同步的延迟通常等几十秒到几分钟就正常了。批量重建流程里我会在删除和创建之间加一段等待或者干脆换个带版本号的新名字避免依赖这个同步时机。第三个坑listAssets返回的是直接子级不是全量。这是设计如此不是 bug。新手常以为列出根目录就能看到所有资产实际只能看到根目录下的第一层。要拿全量必须自己递归前面walk_assets那个栈式遍历就是干这个的。这个误解导致的后果是清理脚本跑完了但磁盘占用没降因为深层目录根本没被扫到。5.3 我个人的操作习惯说几条不在文档里、但我觉得最值钱的经验。永远先小样本验证。任何批量脚本先用 3 到 5 条数据跑一遍完整流程确认清单过滤、路径拼接、权限、日志都正常再放开全量。这个习惯把跑一半发现全错的概率压到极低。日志写到文件不要只打印。终端滚动太快出问题时你根本翻不到关键那几行。我会按delete_YYYYMMDD.log、copy_YYYYMMDD.log的格式落盘每行带时间戳、状态、ID、错误摘要字段用制表符分隔方便后续用命令行工具筛。删除和复制分开两个脚本绝不合并。合并成一个既能删又能复制的工具参数一多就容易在某个分支上搞错方向。两个职责单一的小脚本各跑各的反而更安全。对不可逆的操作宁可多一步人工确认。脚本打印清单后不自动执行而是等你手动加--execute参数。这一步打断感很轻但拦下的错误价值极高。6. 把脚本做成可复用的日常工具单次任务写完就扔下次还得重写这是最浪费的做法。稍微花点时间把脚本整理成可复用的形态后面几个月能省下大量重复劳动。6.1 统一入口与参数化我的做法是做一个命令行入口用参数区分动作和环境。核心参数就四个动作类型delete/copy、输入来源清单文件路径、是否执行dry-run 开关、日志目录。python asset_tool.py delete --plan to_delete.txt --log logs/ python asset_tool.py copy --plan copy_plan.csv --log logs/ --execute这样做的好处是操作意图极其明确命令本身就说明了要干什么。而且 shell 历史记录天然形成一份操作审计哪天想回溯上周我到底跑了什么翻历史命令就有答案。参数校验要做足。清单文件不存在直接报错退出动作类型拼错直接报错退出不要有任何猜一下用户意图的逻辑。工具越笨拙用起来越不容易出事。6.2 日志与回滚准备日志之外我会额外做一件事每次执行的完整清单另存一份到归档目录命名带时间戳。这份归档的价值在于如果事后发现删错了你可以立刻知道误删的是哪个 ID然后去源数据或者备份里找回来。虽然 GEE 本身没有回滚但你至少知道该恢复什么。复制场景的回滚则是反向操作——把刚复制过去的目标资产删掉。所以复制脚本的日志里必须完整记录每一组source - destination的映射这样回滚时可以直接从日志生成删除清单不需要重新推导。6.3 定时清理的思路如果项目有持续导入的习惯临时资产会源源不断产生。我的做法是定一个每周的清理窗口用脚本自动扫出满足条件的资产生成待删清单人工审一遍后再执行。条件通常是这样组合的创建时间在 30 天前、路径里带tmp或test、类型是IMAGE且不在任何正式集合里。自动扫清单、自动执行这一步我始终没有做因为自动删除的风险收益比不划算。扫清单可以自动化删不删这个决定必须有人过一眼。这是我踩过坑之后定下的规矩也建议你在自己的流程里保留这道人工闸口。对于确实需要长期自动化的场景比如某些中间结果每天生成每天清那就用固定的目录约定——中间结果一律落在tmp/daily/下清理脚本只认这个目录、只清 24 小时前的、而且只删IMAGE类型。用目录和类型的双重约束把风险圈死比任何复杂的判断逻辑都可靠。