airmosaic-ai

ERA5 第一次使用：注册、授权、API 与验收

公开流程复核日期：2026-10-26。先完成 ERA5 单层，再推进 CAMS EAC4、CAMS 预报、PM2.5 站点归档和均一化产品。每次只核验一种来源，完成一个步骤再进入下一个；此页提供操作指导，没有实现下载器或 run-tool 入口。

真实操作的开始/完成时间统一记录为北京时间 YYYY-MM-DD HH:mm:ss +08:00。只记录实际发生的操作，未来步骤标为待完成，不预填成功或预计完成时间。成员自己的时间线保留在 Git 外，公开文档只记录通用流程和复核日期。

1. 注册或登录：由本人完成

  1. 打开 CDS 首页，点击 Login / Register。页面可能使用不同的短横线排版。
  2. 已有账户就使用既有账户登录；没有账户再选择注册，按官方页面填写必需信息、设置密码并完成可能的邮箱验证。注册表、个人资料和登录挑战由本人操作，agent 不读取输入值。
  3. 如出现站点条款、隐私或注册确认，先由本人阅读和决定是否接受。不要为排查错误反复新建账户。
  4. 登录跳转后回到 CDS，打开 ERA5 单层产品页。核对 CDS 本身的会话状态；身份提供方登录成功，不代表 CDS 回调已经完成。
  5. 仅在页面不再要求登录，并能继续访问所需的受限操作时，记录登录已确认。只隐藏登录按钮还不足以证明 API 权限；个人姓名、邮箱和头像不进入共享记录。

注册信息与许可由 CDS 服务条款及当前页面决定，不复制个人填写内容。账户资料应由本人维护；不能从错误提示推断账户身份或权限。

出现 OAuthCallback 或仍显示登录入口

这表示 CDS 会话尚未确认，不能据此断定密码错误、API 令牌失效或账户被停用。

  1. 记录错误类别和时间，不记录 OAuth 查询参数、授权码、state、cookie、完整回调地址或原始日志。
  2. 从 CDS 的公开产品页重新使用一次正常登录入口，核对最后是否返回 CDS。不要重复刷新回调地址或不断点击登录。
  3. 如需密码、邮箱验证码或其他挑战，由本人完成。agent 不检查密码框的值，不读取令牌页面、剪贴板或认证存储，也不导出浏览器会话。
  4. 若仍失败，由本人检查当前浏览器提示和官方服务状态，必要时联系官方支持；不关闭安全检查、注入令牌或自行修改浏览器隐私/网络设置。若需换浏览器，须由本人在目标浏览器重新登录，不能复制认证状态。

内置浏览器的现有登录态由宿主管理；没有证据时，不宣称其 profile 位于 AIRMOSAIC_AUTH_DIR。不为套用路径约定擅自迁移、复制或清理现有会话。

2. 接受具体数据集条款：由本人确认

  1. 在上述 ERA5 产品页切换到 Download。
  2. 确认产品名称是 ERA5 hourly data on single levels，官方 ID 为 reanalysis-era5-single-levels。
  3. 找到页面底部的 Terms of Use 或许可证区域。若许可证已显示 Accepted，记录已有接受状态，不重复提交；否则由本人阅读并完成需要的接受动作。站点注册、网页登录和具体数据集许可是不同步骤。
  4. 记录“页面显示已接受 / 本人确认已接受 / 待确认”、证据类型和检查时间。页面已有 Accepted 不能推算当初接受的日期，也不证明 API token 可用。不要保存账户页截图；若 agent 代为执行新的接受动作，必须先取得该动作当时的明确确认，本向导默认由本人操作。

官方要求从数据集页面手动接受适用条款，见 CDS API 指南。不要用重复 API 请求试探许可是否已经生效。

3. 获取 API 访问令牌：仅本人查看

  1. 本人打开 CDS API 设置页，确保仍在 CDS 官方站点。
  2. 找到 API personal access token 的设置/显示区域；名称和位置以当前页面为准。如需创建或重置凭据，由本人完成。
  3. API endpoint 是公开地址 https://cds.climate.copernicus.eu/api；个人 token 是秘密，不能发到聊天、截图、代码、JSON、命令行参数或 Git。
  4. 优先由本人在密码/秘密管理器保管 token。本人也可自行维护官方客户端使用的 .cdsapirc 并明确授权该客户端复用；agent 只记录“本人已准备 / 未准备”，不打开文件或核对值、长度、前后缀。共享说明只写通用文件名，不写成员的真实主目录。
  5. API 设置页可能直接显示秘密。本人查看时暂停 agent 对该页面的 DOM、截图、剪贴板和日志读取；结束后先返回普通产品页，再通知 agent 继续。

官方示例使用 .cdsapirc。AirMosaic 不自动创建、修改、复制或扫描秘密文件；对本人已配置且明确授权的文件，可交给官方客户端在本机内部读取。API 示例支持 prompt（本人隐藏输入）和 existing_file（ERA5、明确授权复用已有默认文件）两种模式，均固定公开 endpoint 并保持 TLS 验证，详见凭据选择说明。网页下载不需要这个文件，也不将浏览器会话转换成 API token。

若本人告知文件已更新，跳过再次索取 token 的步骤，只记录“由本人准备，认证未验证”。后续独立 API 任务中才由客户端实际使用；不能在文档维护时以“检查配置”为由读取或实例化会加载它的客户端。

4. 准备本地环境：可由 agent 检查

先从仓库根目录按环境示例显式加载已审查的个人配置。三根必须存在、彼此不包含，并在 Git checkout 外：

变量 此流程使用方式
AIRMOSAIC_CONFIG_DIR copernicus/ 内的非秘密请求、批次计划和成员任务脚本；只读取明确选中的文件
AIRMOSAIC_ASSETS_DIR results/<project_id>/<run_id>/<stage>/era5/ 放本次新文件；results/<project_id>/<run_id>/records/<tool_id>/ 放脱敏进度与验收摘要
AIRMOSAIC_AUTH_DIR 仅用于另行明确配置的专用认证会话；不存明文 API token，不自动接管内置浏览器
  1. 只核对上述路径及文件元数据，不遍历个人 config/auth 或既有数据目录。
  2. 在项目虚拟环境安装/检查官方客户端。官方当前指南要求 cdsapi>=0.7.7；记录实际版本。网页下载不需要这个包。
  3. 如 pip 提示 SOCKS 支持依赖缺失，先定位为包管理器的代理依赖问题，不能当作 CDS 登录失败。由环境维护者修复依赖，或使用已审查且支持现有网络配置的包管理器；不回显代理设置，也不关闭 TLS 检查或擅自绕过代理。
  4. 请求示例选 ERA5 单层 JSON。只复制选中的非秘密文件到个人配置，不覆盖已有任务设置。

安装客户端不等于已经认证；读取包版本不调用 API。目录约定和路径预检不是 OS 沙箱。

5. 准备最小请求，选择网页或 API

先审查下列演示范围，而不是直接提交全球或多年数据：

项目 仓库演示选择
产品 单层 ERA5，reanalysis
变量 2m_temperature
时间 2024-01-01，00:00 UTC；仅一个时次，不能计算日均
区域 北 40、西 110、南 35、东 115；顺序是北、西、南、东
格式 GRIB，unarchived；修改格式要同步输出扩展名和解码依赖
  1. 在数据集 Download 表单选择上述范围，展开 Show API request code，核对 dataset/request。只保存非秘密参数，不保存签名链接、认证头或页面完整内容。
  2. 本次演示只是拟定的技术验证范围。执行前把产品、变量、日期、区域、文件位置和请求数量在当前任务中明确下来；有覆盖该范围的授权后直接推进，不重复征求同一授权。

A. 网页下载

  1. 沿用本人 CDS 会话，在 Download 表单核对上述少量参数、平均时段和格式；确认条款已接受。
  2. 在已有任务授权范围内点击 Submit form，记录提交时间；等待页面任务状态变化。不必为网页下载配置或查看 API token。
  3. 从页面的任务/请求入口查看排队、完成或失败状态，入口名称以当前页面为准。失败先看已有任务，不重复点击提交。
  4. 完成后保存到 AIRMOSAIC_ASSETS_DIR/results/<project_id>/<run_id>/<stage>/era5/。若先落到系统下载目录，只处理本次文件，按授权移动并核对实际落盘；不扫描其他下载。
  5. 记录保存时间和文件层/内容层检查结果。不导出 cookie、不复制签名下载链接或账户页截图到共享说明。

B. Python API 下载

  1. 按 Python 人工示例准备并审查个人任务脚本。当前向导没有独立下载器或 run-tool 入口。
  2. 明确选择凭据模式：默认 prompt 由本人在终端隐藏输入；本人已维护默认秘密文件并明确授权复用时，将 credential_mode 设为 existing_file。本向导选择 ERA5；ADS 的产品与地址按 CAMS EAC4 示例单独设置。
  3. 在独立任务进程中启动脚本。已有文件模式由官方客户端读取，agent 不打开/打印/解析文件；隐藏输入模式不读取终端输入或回显。两种模式都固定 CDS endpoint、保持 TLS 验证，并检查同一组工作区/配置/认证根边界。
  4. 只提交一个请求，记录开始与完成/失败时间。超时后先核对已有任务，不能不断提交同一请求。脚本异常或客户端对象可能含私人路径/链接，不直接发布原始输出。
  5. 保存文件后按下一节验收；凭据已配置、客户端已安装或文件存在，分别只代表对应阶段完成，不能代替真实 API 与内容验证。

两条路线任选一条进行本轮获取；比较两种方式时要单独限定验证任务，避免同一参数被无意重复提交。项目不自动在网页/API 之间切换，也不把下载完成自动串联到模型计算。

官方 2026-10-22 服务公告建议有效请求顺序提交，避免并行和大量批次。该公告不能用于诊断某一次 OAuthCallback 的具体原因。

6. 验收与记录

  1. 核对 API 任务状态、实际落盘和非零文件，排除错误 HTML 或未完成传输。
  2. 使用对应的 GRIB/NetCDF 解码依赖核对变量、时间、区域、网格、单位和缺失。
  3. 原文件保留在本次输出目录，校验和、非秘密请求副本与验收摘要单独保存；不发布缓存、不启动汇总或建模。
  4. 记录网页登录、许可、凭据准备、API 请求、文件保存和内容检查的状态及完成时间。

时间线保存在 AIRMOSAIC_ASSETS_DIR/results/<project_id>/<run_id>/records/<tool_id>/progress.json，记录阶段、开始/完成时间、证据类型、脱敏结果、下一步及未验证项即可。成员目录、账户、凭据、OAuth 参数、原始异常和下载签名链接均不写入记录。共享时另生成审查过的通用结论，不直接复制私人进度文件。

ERA5 单层 API 下载示例已于 2026-10-26 完成实测，参数、调用步骤和结果见使用示例。

This site is open source. Improve this page.