Granta MI Scripting Toolkit 是材料信息管理平台 Granta MI 提供的编程访问入口在需要批量、重复、定时导出材料数据时它比界面手工导出要可靠得多。实际项目中开发者常用它把 Granta MI 里的材料记录、属性、表格数据和关联文件同步到本地、数据仓库或下游系统也会用它生成定期材料数据快照。这个主题的学习难点不在单个语法而在连上服务器后如何正确查询记录、读取属性、处理编码、写出文件并在失败时能快速定位问题。本文围绕使用 Granta MI Scripting Toolkit 导出数据这条主线从环境准备、最小脚本、细节处理和定时调度几个方面展开适合负责材料数据管理、需要把 MI 数据接入外部系统的开发者阅读。1. 先理解 Scripting Toolkit 在材料数据导出中的定位1.1 从界面导出到脚本导出的变化Granta MI 自带查询界面和导出功能适用于临时取数、人工确认、数据量比较小的场景。界面操作虽然直观但要重复导出同一批材料属性、每周生成一次报告、或把数据交给下游系统时手工导出很难保证每次的查询条件、显示字段、文件格式完全一致。稍微改一个筛选条件就可能漏掉几十条记录而且操作过程难以审计。Scripting Toolkit 的价值在于把“连接、查询、取属性、写文件”变成可保存、可版本管理、可重复执行的代码。脚本一旦写好每次执行结果都基于同一套逻辑。即使下游系统需要调整字段也只需要修改代码里的属性列表和输出格式不需要在界面上重复点击。1.2 适合用脚本导出的典型场景在实际落地时以下几类场景最容易从界面导出迁移到脚本导出每月或每周生成材料属性快照用于项目归档。把 Granta MI 中的材料数据同步到数据仓库、ERP 或自研选材系统。在系统迁移或数据治理前对全量材料数据做一次可审计的导出。将材料数据接入数据分析流程例如训练材料性能预测模型。将 MI 中的表格数据、曲线数据、附件文件批量导出到共享盘或对象存储。这些场景的共同点是数据量大、执行频率稳定、输出结果需要被后续程序消费。脚本导出比手工导出更适合自动化也更容易与现有运维体系结合。1.3 脚本导出的核心不只是“生成文件”脚本导出真正的价值是让数据导出结果可重复、可校验、可追溯。很多初级脚本只是把数据打印到屏幕或者覆盖写一个 CSV缺少日志、行数统计和异常处理。这样的脚本在测试环境能跑进入生产后就很难排查不知道哪一次导出成功不知道文件里是否包含全部记录也不知道失败发生在连接阶段还是写入阶段。因此一个合格的导出脚本至少要在输出文件中记录三方面信息导出时间、导出的记录范围、成功记录数。如果出现异常还应当把异常类型、堆栈和当时的查询条件写入日志。后面的章节会围绕这些要求逐步展开。2. 准备运行环境Python、SDK 和连接参数2.1 环境要求Granta MI Scripting Toolkit 通常以 Python 包或离线 wheel 文件形式提供。准备环境前先确认几项基础信息项目建议要求说明Python 版本3.8 及以上不同版本 SDK 对 Python 版本要求不同以交付文档为准网络环境能访问 Granta MI 服务器或内网隔离环境需要确认服务器地址、端口、证书是否可达安装包wheel 文件或内部软件源如果无法访问外网优先使用管理员提供的离线包下游依赖openpyxl、pandas、requests 等按实际输出格式和脚本复杂度选择账号只读查询账号即可导出场景不建议使用管理员账号环境准备的关键不是“能装包”而是“连接参数正确”。如果服务器地址、数据库名、账号权限有一点不匹配后续所有脚本都会在连接阶段失败。2.2 安装 Scripting Toolkit在能够访问内部软件源的环境中安装命令通常是pip install grantami-scripting-toolkit如果 Granta MI 部署在隔离内网管理员通常会提供一个 wheel 文件可以使用本地文件安装pip install grantami_scripting_toolkit-xxx-py3-none-any.whl安装完成后可以先查看包是否被正确识别pip show grantami-scripting-toolkit python -c import grantami_scripting_toolkit; print(grantami_scripting_toolkit.__version__)这里的包名、版本号、导入路径以你实际拿到的安装包为准。不同版本之间的连接方法、类名和参数命名可能有差异遇到ModuleNotFoundError时优先检查安装的包名是否写错而不是怀疑代码逻辑。2.3 准备服务器地址、数据库和凭据连接 Granta MI 通常需要以下参数参数含义常见示例serverGranta MI 服务器地址https://mi-server.example.comdatabase要访问的数据库名称MI_Materials_V5username登录账号export_userpassword登录密码或应用密钥从环境变量读取timeout请求超时时间120秒verify_ssl是否校验服务器证书生产环境为True不要把密码明文写在脚本里。推荐从环境变量或密钥管理服务读取。连接示例代码如下import os # 示例连接代码实际类名和参数以当前版本 SDK 为准 from grantami_scripting_toolkit import MiClient client MiClient( serveros.environ[MI_SERVER], databaseos.environ[MI_DATABASE], usernameos.environ[MI_USER], passwordos.environ[MI_PASSWORD], timeout120, )注意下面代码给出的MiClient、query_records、fetch_attributes是流程示意。不同版本的 SDK 可能会有不同的类名和方法名落地前先在你安装的包中打开接口文档或dir(client)确认。3. 编写第一个导出脚本从连接服务器到写出 CSV3.1 导出流程拆解一个最小可用的导出脚本可以拆成六个步骤建立会话连接 Granta MI。确定要导出的表和查询条件。查询符合条件的记录列表。对每条记录读取需要的属性值。把属性值组装成 CSV 行数据。写出文件并记录导出统计信息。这个流程看似简单但每一步都有容易出错的地方。比如查询条件写错会导致空结果属性名写错会导致获取不到值CSV 编码不对会导致 Excel 打开乱码。下面按步骤给出示意实现。3.2 建立会话并查询记录建立会话后第一步是查询记录。以导出名称中包含 “Aluminum” 的材料记录为例records client.query_records( tableMaterial Data, conditionName contains Aluminum, )查询条件通常使用 Granta MI 过滤语法。如果条件为空可以设置conditionNone来导出指定表中的全部记录。注意全部记录导出时数据量可能很大最好先加limit或在 WHERE 条件里缩小范围。3.3 读取属性并构造行数据得到记录列表后需要读取每条记录的具体属性。材料数据库中的属性通常包括密度、抗拉强度、屈服强度、延伸率等header [Record ID, Name, Density, Tensile Strength] rows [] for record in records: values client.fetch_attributes( record_idrecord.record_id, attributes[Density, Tensile Strength], ) rows.append([ record.record_id, record.name, values.get(Density), values.get(Tensile Strength), ])在实际 SDK 中fetch_attributes的返回值可能是字典、列表或带属性的对象。关键是明确每个属性对应的数据类型避免把列表、字典直接写进 CSV。3.4 写出 CSV 并处理中文字节写出 CSV 时推荐使用 Python 标准库csv并指定 UTF-8 with BOM 编码from pathlib import Path import csv out_path Path(material_export.csv) with out_path.open(w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow(header) writer.writerows(rows)使用utf-8-sig的原因是Excel 在打开 CSV 文件时如果文件没有 BOM默认可能按本地 ANSI 编码解析中文字段容易出现乱码。utf-8-sig会在文件头写入 BOM让 Excel 识别为 UTF-8 文件。3.5 一个最小完整脚本把以上步骤合并成一个完整脚本 最小导出脚本示例连接 Granta MI查询记录导出属性到 CSV。 实际类名、方法名、导入路径以你安装的 Scripting Toolkit 版本为准。 import csv import os from pathlib import Path from grantami_scripting_toolkit import MiClient # 示例导入 SERVER os.environ[MI_SERVER] DATABASE os.environ[MI_DATABASE] USERNAME os.environ[MI_USER] PASSWORD os.environ[MI_PASSWORD] client MiClient( serverSERVER, databaseDATABASE, usernameUSERNAME, passwordPASSWORD, timeout120, ) records client.query_records( tableMaterial Data, conditionName contains Aluminum, ) header [Record ID, Name, Density, Tensile Strength] rows [] for record in records: values client.fetch_attributes( record_idrecord.record_id, attributes[Density, Tensile Strength], ) rows.append([ record.record_id, record.name, values.get(Density), values.get(Tensile Strength), ]) out_path Path(material_export.csv) with out_path.open(w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow(header) writer.writerows(rows) print(f导出完成: {out_path.resolve()}, 共 {len(rows)} 条记录)运行脚本前先确认环境变量已经设置好export MI_SERVERhttps://mi-server.example.com export MI_DATABASEMI_Materials_V5 export MI_USERexport_user export MI_PASSWORDyour_password然后执行python export_material_data.py如果连接成功脚本会在当前目录生成material_export.csv并输出导出记录数。4. 导出数据时必须处理的四个细节4.1 给记录带一个唯一标识很多数据库导出工具都有“导出数据没有主键 ID”的问题。DBeaver 导出表数据时如果只选择了业务字段而漏了主键后续要用脚本核对哪一行被修改、哪一行需要回写会非常困难。Granta MI 脚本导出也是同样道理。导出记录时至少要携带一个能唯一标识记录的字段。Granta MI 中常见的是记录 ID、History GUID 或记录名称。名称不一定是唯一的两个不同批次但名称相同的材料可能同时存在只导出名称会导致后续无法区分记录。建议在导出表头中增加以下字段字段说明Record ID记录在当前数据库中的唯一编号Record History GUID记录历史版本标识适合追踪变更Name记录名称便于人工阅读Last Modified Date最后修改时间适合增量导出判断这样导出的数据即使脱离了 Granta MI 界面也能通过唯一标识定位到原始记录。4.2 中文字段乱码的根源与处理中文乱码是导出任务里最常见的问题之一。它的根源通常是“写入编码”与“读取编码”不一致。在 Granta MI 脚本导出场景中可能出现乱码的位置有三个第一脚本读取数据时CSV 写出使用了系统默认编码。在 Windows 中文环境下Python 的默认编码可能是 GBK在 Linux 环境下可能是 UTF-8。同一个脚本在不同服务器上运行结果不一样。第二CSV 文件本身是 UTF-8 无 BOMExcel 却按本地 ANSI 解析。这个问题在前面已经提到解决方案是使用utf-8-sig编码写出。第三下游系统按 GB2312 或 GB18030 读取文件但文件实际是 UTF-8。这种场景需要提前确认下游编码要求。推荐做法如下场景推荐编码说明文件由 Excel 直接打开utf-8-sig带 BOM兼容性最好文件由 Linux 脚本读取utf-8不带 BOM避免多余字符老版本中文 Excelgb18030兼容繁体简体但要注意下游编码约束如果导出结果用于数据仓库或 BI 工具优先使用utf-8如果结果需要业务人员用 Excel 打开优先使用utf-8-sig。4.3 表格数据和文件类型属性不能简单拍平Granta MI 中的材料数据不只包含密度、强度这类单值属性还包含曲线数据、多层表格、图片、PDF 附件等。把这类数据简单“拍平”成一个字段写入 CSV会丢失数据结构。表格数据建议按“一主多子”的方式处理主文件保存记录基础属性子表单独导出成另一个 CSV 或另一个 Excel Sheet并通过 Record ID 关联。文件类型属性建议导出为独立文件同时生成一个元数据清单记录文件对应哪个 Record ID、哪个属性、保存路径和文件名。示例输出结构export/ metadata.csv records.csv attachments/ record_10001_datasheet.pdf record_10002_curve.png record_10003_test_report.pdfmetadata.csv至少包含 Record ID、属性名、文件名、大小、保存路径。这样附件和主数据在后续处理时可以重新关联。4.4 大批量导出要控制内存和请求次数如果一次性查询几千条记录并把所有记录的所有属性都加载到内存脚本可能运行到一半就内存溢出或请求超时。处理大量数据时建议采用分批获取的方式先查询记录 ID 列表不加载全部属性。每 100 条或 200 条记录为一个批次逐批读取属性。每个批次读取后立即写入文件释放内存。这种做法的好处是避免服务端单次响应过大也方便在某个批次失败时重新执行而不需要重新查询全部记录。5. 运行验证不要以“能打开文件”作为通过标准5.1 文件完整性检查脚本跑完后需要验证生成的文件是否完整。常见检查项包括文件是否生成路径是否正确。文件大小是否在预期范围内。CSV 表头是否和预期字段一致。空文件是否意味着查询条件或权限有问题。一个常见的错误是脚本连接成功但查询条件写错导出的 CSV 只有表头没有数据。只看“文件能打开”发现不了这个问题必须核对记录数。5.2 行数与关键字段校验推荐在脚本中加入一个异步或独立的校验步骤重新读取生成的 CSV统计行数并和查询到的记录数对比。也可以手工在 Granta MI 界面执行同样的查询对比记录数。一个简单的 Python 校验方法import csv expected_count len(records) with open(material_export.csv, newline, encodingutf-8-sig) as f: reader csv.reader(f) header next(reader) exported_count sum(1 for _ in reader) print(表头:, header) print(期望记录数:, expected_count) print(实际记录数:, exported_count)如果两个数字不一致优先检查查询条件、分页逻辑和数据修改时间。还需要注意导出过程中如果其他用户正在修改数据可能出现导出时记录数和服务端实际数据不一致的情况。5.3 编码与字段类型检查编码问题不能等 Excel 打开后才能发现。可以在脚本里加入自动检查检查项方法通过标准CSV 编码用openpyxl或chardet检测文件编码与预期编码一致中文字段抽样读取几行打印字段值没有乱码字符数字字段抽样校验类型和范围数值格式正确没有None混入文本记录数重新读取文件统计与查询结果一致注意验证脚本本身也要纳入自动化流程。每次导出后至少执行一次校验否则导出质量问题要到下游使用数据时才会暴露。6. 工程化配置外置、定时任务和日志6.1 为什么建议把连接信息放到脚本外面生产环境中的脚本不应该把服务器地址、数据库名、密码写成硬编码。配置外置的目的有三个不同环境之间切换时不需要改代码敏感信息不会进入版本库运维人员可以直接修改配置而不需要接触代码。常见的配置外置方式包括环境变量、INI/XML 配置文件、配置中心或密钥管理服务。对中小项目而言XML 配置文件已经足够直观。6.2 用 XML 文件管理导出任务下面是一个导出任务配置示例包含保存路径、调度时间、服务器信息、数据库名称和要导出的表?xml version1.0 encodingutf-8? config xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:xsdhttp://www.w3.org/2001/XMLSchema savepathD:\data_export\材料数据 cron0 0 2 * * ? serverhttps://mi-server.example.com/server databaseMI_Materials_V5/database exportTables table nameTensile Properties formatexcel/ table namePhysical Properties formatcsv/ /exportTables /config配置字段说明字段含义savepath导出文件保存目录cron定时触发表达式Quartz 风格server连接服务器地址database访问的数据库名称exportTables要导出的数据表列表table/format输出格式可选 csv 或 excel使用 Python 解析这个配置import xml.etree.ElementTree as ET tree ET.parse(export_config.xml) root tree.getroot() save_path root.attrib[savepath] cron root.attrib.get(cron, 0 0 2 * * ?) server root.findtext(server) database root.findtext(database) tables [] for table in root.findall(exportTables/table): tables.append({ name: table.attrib[name], format: table.attrib.get(format, csv), })这种方式适合把调度任务和导出逻辑解耦。运维人员只需要维护 XML 配置不需要改 Python 代码。6.3 定时调度方式导出脚本工程化后通常会交给调度系统定时执行。不同平台的写法不同Windows 计划任务可以使用schtasks命令schtasks /create /tn GrantaExport /tr python D:\scripts\export_runner.py /sc daily /st 02:00Linux 可以使用 crontab0 2 * * * cd /opt/granta-export python export_runner.py logs/export.log 21如果使用 Quartz 风格表达式0 0 2 * * ?表示每天凌晨 2 点触发。不同调度框架对字段含义的处理不同配置前应和调度系统文档核对。6.4 日志落盘和失败告警定时任务和手工执行的区别在于手工执行时人能发现报错定时任务失败时可能没有任何人察觉。因此必须把日志落到文件并设置失败通知。建议每条日志记录以下内容2025-06-01 02:00:01 [INFO] 导出任务开始数据库MI_Materials_V5 2025-06-01 02:00:15 [INFO] 查询记录完成records1280 2025-06-01 02:00:32 [INFO] 写入文件完成pathD:\data_export\材料数据\records.csv 2025-06-01 02:00:32 [INFO] 校验通过exported1280 2025-06-01 02:00:33 [INFO] 导出任务结束如果出现异常至少记录异常类型、堆栈、查询条件和当前处理到的记录位置。生产环境可以在此基础上接入邮件、企业微信、钉钉或统一告警平台。7. 常见坑与排查链路7.1 高频问题速查问题现象常见原因检查方式处理建议连接超时网络不通、服务器端口未放开使用 curl 测试服务器端口确认网络策略、代理设置和超时参数返回 401/403账号密码错误或账号无权限检查账号和数据库权限使用最小权限只读账号确认角色导出结果为空数据库选错、查询条件过严在 Granta MI 界面手工查询对比打印查询条件确认表名和条件语法CSV 中文乱码文件编码和读取编码不一致用文本编辑器检查编码写出时使用utf-8-sig或按下游要求转码文件写入失败保存目录不存在或权限不足检查目录和权限脚本启动前自动创建目录并检查可写大批量导出卡死一次请求加载数据过多查看日志和服务端负载分批获取限制每批记录数脚本执行时间过长导致会话失效会话超时策略查看会话超时配置在读取前重新认证或延长会话超时时间SSL 证书校验失败内网证书不受信任查看证书链测试环境可临时关闭校验生产环境必须导入 CA 证书7.2 从现象倒推根因的排查顺序遇到导出问题时按以下顺序排查能避免在错误方向浪费时间检查输入参数。确认 XML 配置、环境变量中的服务器地址、数据库、保存路径是否正确。检查网络和证书。服务器能否 ping 通端口是否开放证书链是否完整。检查账号权限。当前账号是否有查询该表、读取该属性的权限。检查查询条件。在 Granta MI 界面手工执行同样条件对比结果。检查代码版本和 SDK 版本。确认脚本里的类名、方法名和当前 SDK 版本一致。检查日志和异常。优先看异常类型和堆栈而不是盲目改代码。与服务端管理员确认限制。确认是否存在单次查询数量限制、连接数限制或备份窗口。7.3 两个排查实例实例一Excel 打开 CSV 中文乱码现象是脚本生成的 CSV 用记事本打开正常用 Excel 打开乱码。原因是文件没有 BOMExcel 默认按本地 ANSI 解析。解决方法是把写出编码改为utf-8-sig。如果文件已经生成可以用文本编辑器另存为带 BOM 的 UTF-8或转换成gb18030。预防手段是在脚本写出后自动检查文件编码。实例二定时任务偶尔导出行数不全现象是每天凌晨导出的材料数据大部分时间正常偶尔少几十条。排查时先看日志发现失败批次的记录数和成功批次有明显差异。进一步检查发现调度时间和服务端备份窗口重叠读取时部分记录处于非稳定状态。另一种常见原因是增量导出的时间边界没有固定导致因时区或调度延迟遗漏记录。处理方法是把调度时间避开备份窗口并在每次导出前记录本次导出的时间范围用于下次增量判断。8. 生产环境最佳实践与扩展方向8.1 生产环境落地清单清单项建议账号权限使用只读账号不开放写权限凭据管理密码从环境变量或密钥服务读取不落入代码库日志每次导出记录时间、记录数、文件路径、异常信息校验导出后自动核对记录数和关键字段告警失败时通过邮件或企业消息通知责任人调度避开服务端备份窗口设置超时和重试文件清理定期清理历史导出文件避免磁盘写满版本管理导出脚本进入 Git配置与代码分离回滚方案保留上一次导出结果新版本脚本异常时可快速回退8.2 通用导出任务的共性经验Granta MI 脚本导出和 MySQL、Oracle、DBeaver、IDEA Database 中的数据导出有很多共性。无论从哪种系统导出数据都要关注连接字符集、唯一标识、NULL 值处理和行数校验。比如 DBeaver 导出表数据时漏掉主键会导致回写和比对困难Oracle 导出中文乱码通常也是连接字符集和客户端编码不一致造成的。把这些经验沉淀成统一的导出规范比每次遇到问题再临时排查更有效。8.3 后续扩展方向如果导出脚本已经在生产环境稳定运行下一步可以考虑增量导出。利用Last Modified Date或Record History GUID只导出修改过的记录减少数据量和执行时间。配置中心化。从 XML 配置迁移到更完整的配置中心支持在线修改和版本审计。结果元数据化。导出时同时生成一份 JSON 元数据描述导出时间、来源库、查询条件、字段映射方便下游自动解析。与数据看板集成。把导出的材料数据接入 BI 工具或数据中台替代人工定期更新报表。把导出脚本升级成数据订阅服务后通常会遇到权限、增量计算和调度可靠性三个问题。这也是 Granta MI 数据工程化过程中最值得继续投入的方向。 Granta MI Scripting Toolkit：Python自动化导出材料数据实践
Granta MI Scripting Toolkit 是材料信息管理平台 Granta MI 提供的编程访问入口在需要批量、重复、定时导出材料数据时它比界面手工导出要可靠得多。实际项目中开发者常用它把 Granta MI 里的材料记录、属性、表格数据和关联文件同步到本地、数据仓库或下游系统也会用它生成定期材料数据快照。这个主题的学习难点不在单个语法而在连上服务器后如何正确查询记录、读取属性、处理编码、写出文件并在失败时能快速定位问题。本文围绕使用 Granta MI Scripting Toolkit 导出数据这条主线从环境准备、最小脚本、细节处理和定时调度几个方面展开适合负责材料数据管理、需要把 MI 数据接入外部系统的开发者阅读。1. 先理解 Scripting Toolkit 在材料数据导出中的定位1.1 从界面导出到脚本导出的变化Granta MI 自带查询界面和导出功能适用于临时取数、人工确认、数据量比较小的场景。界面操作虽然直观但要重复导出同一批材料属性、每周生成一次报告、或把数据交给下游系统时手工导出很难保证每次的查询条件、显示字段、文件格式完全一致。稍微改一个筛选条件就可能漏掉几十条记录而且操作过程难以审计。Scripting Toolkit 的价值在于把“连接、查询、取属性、写文件”变成可保存、可版本管理、可重复执行的代码。脚本一旦写好每次执行结果都基于同一套逻辑。即使下游系统需要调整字段也只需要修改代码里的属性列表和输出格式不需要在界面上重复点击。1.2 适合用脚本导出的典型场景在实际落地时以下几类场景最容易从界面导出迁移到脚本导出每月或每周生成材料属性快照用于项目归档。把 Granta MI 中的材料数据同步到数据仓库、ERP 或自研选材系统。在系统迁移或数据治理前对全量材料数据做一次可审计的导出。将材料数据接入数据分析流程例如训练材料性能预测模型。将 MI 中的表格数据、曲线数据、附件文件批量导出到共享盘或对象存储。这些场景的共同点是数据量大、执行频率稳定、输出结果需要被后续程序消费。脚本导出比手工导出更适合自动化也更容易与现有运维体系结合。1.3 脚本导出的核心不只是“生成文件”脚本导出真正的价值是让数据导出结果可重复、可校验、可追溯。很多初级脚本只是把数据打印到屏幕或者覆盖写一个 CSV缺少日志、行数统计和异常处理。这样的脚本在测试环境能跑进入生产后就很难排查不知道哪一次导出成功不知道文件里是否包含全部记录也不知道失败发生在连接阶段还是写入阶段。因此一个合格的导出脚本至少要在输出文件中记录三方面信息导出时间、导出的记录范围、成功记录数。如果出现异常还应当把异常类型、堆栈和当时的查询条件写入日志。后面的章节会围绕这些要求逐步展开。2. 准备运行环境Python、SDK 和连接参数2.1 环境要求Granta MI Scripting Toolkit 通常以 Python 包或离线 wheel 文件形式提供。准备环境前先确认几项基础信息项目建议要求说明Python 版本3.8 及以上不同版本 SDK 对 Python 版本要求不同以交付文档为准网络环境能访问 Granta MI 服务器或内网隔离环境需要确认服务器地址、端口、证书是否可达安装包wheel 文件或内部软件源如果无法访问外网优先使用管理员提供的离线包下游依赖openpyxl、pandas、requests 等按实际输出格式和脚本复杂度选择账号只读查询账号即可导出场景不建议使用管理员账号环境准备的关键不是“能装包”而是“连接参数正确”。如果服务器地址、数据库名、账号权限有一点不匹配后续所有脚本都会在连接阶段失败。2.2 安装 Scripting Toolkit在能够访问内部软件源的环境中安装命令通常是pip install grantami-scripting-toolkit如果 Granta MI 部署在隔离内网管理员通常会提供一个 wheel 文件可以使用本地文件安装pip install grantami_scripting_toolkit-xxx-py3-none-any.whl安装完成后可以先查看包是否被正确识别pip show grantami-scripting-toolkit python -c import grantami_scripting_toolkit; print(grantami_scripting_toolkit.__version__)这里的包名、版本号、导入路径以你实际拿到的安装包为准。不同版本之间的连接方法、类名和参数命名可能有差异遇到ModuleNotFoundError时优先检查安装的包名是否写错而不是怀疑代码逻辑。2.3 准备服务器地址、数据库和凭据连接 Granta MI 通常需要以下参数参数含义常见示例serverGranta MI 服务器地址https://mi-server.example.comdatabase要访问的数据库名称MI_Materials_V5username登录账号export_userpassword登录密码或应用密钥从环境变量读取timeout请求超时时间120秒verify_ssl是否校验服务器证书生产环境为True不要把密码明文写在脚本里。推荐从环境变量或密钥管理服务读取。连接示例代码如下import os # 示例连接代码实际类名和参数以当前版本 SDK 为准 from grantami_scripting_toolkit import MiClient client MiClient( serveros.environ[MI_SERVER], databaseos.environ[MI_DATABASE], usernameos.environ[MI_USER], passwordos.environ[MI_PASSWORD], timeout120, )注意下面代码给出的MiClient、query_records、fetch_attributes是流程示意。不同版本的 SDK 可能会有不同的类名和方法名落地前先在你安装的包中打开接口文档或dir(client)确认。3. 编写第一个导出脚本从连接服务器到写出 CSV3.1 导出流程拆解一个最小可用的导出脚本可以拆成六个步骤建立会话连接 Granta MI。确定要导出的表和查询条件。查询符合条件的记录列表。对每条记录读取需要的属性值。把属性值组装成 CSV 行数据。写出文件并记录导出统计信息。这个流程看似简单但每一步都有容易出错的地方。比如查询条件写错会导致空结果属性名写错会导致获取不到值CSV 编码不对会导致 Excel 打开乱码。下面按步骤给出示意实现。3.2 建立会话并查询记录建立会话后第一步是查询记录。以导出名称中包含 “Aluminum” 的材料记录为例records client.query_records( tableMaterial Data, conditionName contains Aluminum, )查询条件通常使用 Granta MI 过滤语法。如果条件为空可以设置conditionNone来导出指定表中的全部记录。注意全部记录导出时数据量可能很大最好先加limit或在 WHERE 条件里缩小范围。3.3 读取属性并构造行数据得到记录列表后需要读取每条记录的具体属性。材料数据库中的属性通常包括密度、抗拉强度、屈服强度、延伸率等header [Record ID, Name, Density, Tensile Strength] rows [] for record in records: values client.fetch_attributes( record_idrecord.record_id, attributes[Density, Tensile Strength], ) rows.append([ record.record_id, record.name, values.get(Density), values.get(Tensile Strength), ])在实际 SDK 中fetch_attributes的返回值可能是字典、列表或带属性的对象。关键是明确每个属性对应的数据类型避免把列表、字典直接写进 CSV。3.4 写出 CSV 并处理中文字节写出 CSV 时推荐使用 Python 标准库csv并指定 UTF-8 with BOM 编码from pathlib import Path import csv out_path Path(material_export.csv) with out_path.open(w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow(header) writer.writerows(rows)使用utf-8-sig的原因是Excel 在打开 CSV 文件时如果文件没有 BOM默认可能按本地 ANSI 编码解析中文字段容易出现乱码。utf-8-sig会在文件头写入 BOM让 Excel 识别为 UTF-8 文件。3.5 一个最小完整脚本把以上步骤合并成一个完整脚本 最小导出脚本示例连接 Granta MI查询记录导出属性到 CSV。 实际类名、方法名、导入路径以你安装的 Scripting Toolkit 版本为准。 import csv import os from pathlib import Path from grantami_scripting_toolkit import MiClient # 示例导入 SERVER os.environ[MI_SERVER] DATABASE os.environ[MI_DATABASE] USERNAME os.environ[MI_USER] PASSWORD os.environ[MI_PASSWORD] client MiClient( serverSERVER, databaseDATABASE, usernameUSERNAME, passwordPASSWORD, timeout120, ) records client.query_records( tableMaterial Data, conditionName contains Aluminum, ) header [Record ID, Name, Density, Tensile Strength] rows [] for record in records: values client.fetch_attributes( record_idrecord.record_id, attributes[Density, Tensile Strength], ) rows.append([ record.record_id, record.name, values.get(Density), values.get(Tensile Strength), ]) out_path Path(material_export.csv) with out_path.open(w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow(header) writer.writerows(rows) print(f导出完成: {out_path.resolve()}, 共 {len(rows)} 条记录)运行脚本前先确认环境变量已经设置好export MI_SERVERhttps://mi-server.example.com export MI_DATABASEMI_Materials_V5 export MI_USERexport_user export MI_PASSWORDyour_password然后执行python export_material_data.py如果连接成功脚本会在当前目录生成material_export.csv并输出导出记录数。4. 导出数据时必须处理的四个细节4.1 给记录带一个唯一标识很多数据库导出工具都有“导出数据没有主键 ID”的问题。DBeaver 导出表数据时如果只选择了业务字段而漏了主键后续要用脚本核对哪一行被修改、哪一行需要回写会非常困难。Granta MI 脚本导出也是同样道理。导出记录时至少要携带一个能唯一标识记录的字段。Granta MI 中常见的是记录 ID、History GUID 或记录名称。名称不一定是唯一的两个不同批次但名称相同的材料可能同时存在只导出名称会导致后续无法区分记录。建议在导出表头中增加以下字段字段说明Record ID记录在当前数据库中的唯一编号Record History GUID记录历史版本标识适合追踪变更Name记录名称便于人工阅读Last Modified Date最后修改时间适合增量导出判断这样导出的数据即使脱离了 Granta MI 界面也能通过唯一标识定位到原始记录。4.2 中文字段乱码的根源与处理中文乱码是导出任务里最常见的问题之一。它的根源通常是“写入编码”与“读取编码”不一致。在 Granta MI 脚本导出场景中可能出现乱码的位置有三个第一脚本读取数据时CSV 写出使用了系统默认编码。在 Windows 中文环境下Python 的默认编码可能是 GBK在 Linux 环境下可能是 UTF-8。同一个脚本在不同服务器上运行结果不一样。第二CSV 文件本身是 UTF-8 无 BOMExcel 却按本地 ANSI 解析。这个问题在前面已经提到解决方案是使用utf-8-sig编码写出。第三下游系统按 GB2312 或 GB18030 读取文件但文件实际是 UTF-8。这种场景需要提前确认下游编码要求。推荐做法如下场景推荐编码说明文件由 Excel 直接打开utf-8-sig带 BOM兼容性最好文件由 Linux 脚本读取utf-8不带 BOM避免多余字符老版本中文 Excelgb18030兼容繁体简体但要注意下游编码约束如果导出结果用于数据仓库或 BI 工具优先使用utf-8如果结果需要业务人员用 Excel 打开优先使用utf-8-sig。4.3 表格数据和文件类型属性不能简单拍平Granta MI 中的材料数据不只包含密度、强度这类单值属性还包含曲线数据、多层表格、图片、PDF 附件等。把这类数据简单“拍平”成一个字段写入 CSV会丢失数据结构。表格数据建议按“一主多子”的方式处理主文件保存记录基础属性子表单独导出成另一个 CSV 或另一个 Excel Sheet并通过 Record ID 关联。文件类型属性建议导出为独立文件同时生成一个元数据清单记录文件对应哪个 Record ID、哪个属性、保存路径和文件名。示例输出结构export/ metadata.csv records.csv attachments/ record_10001_datasheet.pdf record_10002_curve.png record_10003_test_report.pdfmetadata.csv至少包含 Record ID、属性名、文件名、大小、保存路径。这样附件和主数据在后续处理时可以重新关联。4.4 大批量导出要控制内存和请求次数如果一次性查询几千条记录并把所有记录的所有属性都加载到内存脚本可能运行到一半就内存溢出或请求超时。处理大量数据时建议采用分批获取的方式先查询记录 ID 列表不加载全部属性。每 100 条或 200 条记录为一个批次逐批读取属性。每个批次读取后立即写入文件释放内存。这种做法的好处是避免服务端单次响应过大也方便在某个批次失败时重新执行而不需要重新查询全部记录。5. 运行验证不要以“能打开文件”作为通过标准5.1 文件完整性检查脚本跑完后需要验证生成的文件是否完整。常见检查项包括文件是否生成路径是否正确。文件大小是否在预期范围内。CSV 表头是否和预期字段一致。空文件是否意味着查询条件或权限有问题。一个常见的错误是脚本连接成功但查询条件写错导出的 CSV 只有表头没有数据。只看“文件能打开”发现不了这个问题必须核对记录数。5.2 行数与关键字段校验推荐在脚本中加入一个异步或独立的校验步骤重新读取生成的 CSV统计行数并和查询到的记录数对比。也可以手工在 Granta MI 界面执行同样的查询对比记录数。一个简单的 Python 校验方法import csv expected_count len(records) with open(material_export.csv, newline, encodingutf-8-sig) as f: reader csv.reader(f) header next(reader) exported_count sum(1 for _ in reader) print(表头:, header) print(期望记录数:, expected_count) print(实际记录数:, exported_count)如果两个数字不一致优先检查查询条件、分页逻辑和数据修改时间。还需要注意导出过程中如果其他用户正在修改数据可能出现导出时记录数和服务端实际数据不一致的情况。5.3 编码与字段类型检查编码问题不能等 Excel 打开后才能发现。可以在脚本里加入自动检查检查项方法通过标准CSV 编码用openpyxl或chardet检测文件编码与预期编码一致中文字段抽样读取几行打印字段值没有乱码字符数字字段抽样校验类型和范围数值格式正确没有None混入文本记录数重新读取文件统计与查询结果一致注意验证脚本本身也要纳入自动化流程。每次导出后至少执行一次校验否则导出质量问题要到下游使用数据时才会暴露。6. 工程化配置外置、定时任务和日志6.1 为什么建议把连接信息放到脚本外面生产环境中的脚本不应该把服务器地址、数据库名、密码写成硬编码。配置外置的目的有三个不同环境之间切换时不需要改代码敏感信息不会进入版本库运维人员可以直接修改配置而不需要接触代码。常见的配置外置方式包括环境变量、INI/XML 配置文件、配置中心或密钥管理服务。对中小项目而言XML 配置文件已经足够直观。6.2 用 XML 文件管理导出任务下面是一个导出任务配置示例包含保存路径、调度时间、服务器信息、数据库名称和要导出的表?xml version1.0 encodingutf-8? config xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:xsdhttp://www.w3.org/2001/XMLSchema savepathD:\data_export\材料数据 cron0 0 2 * * ? serverhttps://mi-server.example.com/server databaseMI_Materials_V5/database exportTables table nameTensile Properties formatexcel/ table namePhysical Properties formatcsv/ /exportTables /config配置字段说明字段含义savepath导出文件保存目录cron定时触发表达式Quartz 风格server连接服务器地址database访问的数据库名称exportTables要导出的数据表列表table/format输出格式可选 csv 或 excel使用 Python 解析这个配置import xml.etree.ElementTree as ET tree ET.parse(export_config.xml) root tree.getroot() save_path root.attrib[savepath] cron root.attrib.get(cron, 0 0 2 * * ?) server root.findtext(server) database root.findtext(database) tables [] for table in root.findall(exportTables/table): tables.append({ name: table.attrib[name], format: table.attrib.get(format, csv), })这种方式适合把调度任务和导出逻辑解耦。运维人员只需要维护 XML 配置不需要改 Python 代码。6.3 定时调度方式导出脚本工程化后通常会交给调度系统定时执行。不同平台的写法不同Windows 计划任务可以使用schtasks命令schtasks /create /tn GrantaExport /tr python D:\scripts\export_runner.py /sc daily /st 02:00Linux 可以使用 crontab0 2 * * * cd /opt/granta-export python export_runner.py logs/export.log 21如果使用 Quartz 风格表达式0 0 2 * * ?表示每天凌晨 2 点触发。不同调度框架对字段含义的处理不同配置前应和调度系统文档核对。6.4 日志落盘和失败告警定时任务和手工执行的区别在于手工执行时人能发现报错定时任务失败时可能没有任何人察觉。因此必须把日志落到文件并设置失败通知。建议每条日志记录以下内容2025-06-01 02:00:01 [INFO] 导出任务开始数据库MI_Materials_V5 2025-06-01 02:00:15 [INFO] 查询记录完成records1280 2025-06-01 02:00:32 [INFO] 写入文件完成pathD:\data_export\材料数据\records.csv 2025-06-01 02:00:32 [INFO] 校验通过exported1280 2025-06-01 02:00:33 [INFO] 导出任务结束如果出现异常至少记录异常类型、堆栈、查询条件和当前处理到的记录位置。生产环境可以在此基础上接入邮件、企业微信、钉钉或统一告警平台。7. 常见坑与排查链路7.1 高频问题速查问题现象常见原因检查方式处理建议连接超时网络不通、服务器端口未放开使用 curl 测试服务器端口确认网络策略、代理设置和超时参数返回 401/403账号密码错误或账号无权限检查账号和数据库权限使用最小权限只读账号确认角色导出结果为空数据库选错、查询条件过严在 Granta MI 界面手工查询对比打印查询条件确认表名和条件语法CSV 中文乱码文件编码和读取编码不一致用文本编辑器检查编码写出时使用utf-8-sig或按下游要求转码文件写入失败保存目录不存在或权限不足检查目录和权限脚本启动前自动创建目录并检查可写大批量导出卡死一次请求加载数据过多查看日志和服务端负载分批获取限制每批记录数脚本执行时间过长导致会话失效会话超时策略查看会话超时配置在读取前重新认证或延长会话超时时间SSL 证书校验失败内网证书不受信任查看证书链测试环境可临时关闭校验生产环境必须导入 CA 证书7.2 从现象倒推根因的排查顺序遇到导出问题时按以下顺序排查能避免在错误方向浪费时间检查输入参数。确认 XML 配置、环境变量中的服务器地址、数据库、保存路径是否正确。检查网络和证书。服务器能否 ping 通端口是否开放证书链是否完整。检查账号权限。当前账号是否有查询该表、读取该属性的权限。检查查询条件。在 Granta MI 界面手工执行同样条件对比结果。检查代码版本和 SDK 版本。确认脚本里的类名、方法名和当前 SDK 版本一致。检查日志和异常。优先看异常类型和堆栈而不是盲目改代码。与服务端管理员确认限制。确认是否存在单次查询数量限制、连接数限制或备份窗口。7.3 两个排查实例实例一Excel 打开 CSV 中文乱码现象是脚本生成的 CSV 用记事本打开正常用 Excel 打开乱码。原因是文件没有 BOMExcel 默认按本地 ANSI 解析。解决方法是把写出编码改为utf-8-sig。如果文件已经生成可以用文本编辑器另存为带 BOM 的 UTF-8或转换成gb18030。预防手段是在脚本写出后自动检查文件编码。实例二定时任务偶尔导出行数不全现象是每天凌晨导出的材料数据大部分时间正常偶尔少几十条。排查时先看日志发现失败批次的记录数和成功批次有明显差异。进一步检查发现调度时间和服务端备份窗口重叠读取时部分记录处于非稳定状态。另一种常见原因是增量导出的时间边界没有固定导致因时区或调度延迟遗漏记录。处理方法是把调度时间避开备份窗口并在每次导出前记录本次导出的时间范围用于下次增量判断。8. 生产环境最佳实践与扩展方向8.1 生产环境落地清单清单项建议账号权限使用只读账号不开放写权限凭据管理密码从环境变量或密钥服务读取不落入代码库日志每次导出记录时间、记录数、文件路径、异常信息校验导出后自动核对记录数和关键字段告警失败时通过邮件或企业消息通知责任人调度避开服务端备份窗口设置超时和重试文件清理定期清理历史导出文件避免磁盘写满版本管理导出脚本进入 Git配置与代码分离回滚方案保留上一次导出结果新版本脚本异常时可快速回退8.2 通用导出任务的共性经验Granta MI 脚本导出和 MySQL、Oracle、DBeaver、IDEA Database 中的数据导出有很多共性。无论从哪种系统导出数据都要关注连接字符集、唯一标识、NULL 值处理和行数校验。比如 DBeaver 导出表数据时漏掉主键会导致回写和比对困难Oracle 导出中文乱码通常也是连接字符集和客户端编码不一致造成的。把这些经验沉淀成统一的导出规范比每次遇到问题再临时排查更有效。8.3 后续扩展方向如果导出脚本已经在生产环境稳定运行下一步可以考虑增量导出。利用Last Modified Date或Record History GUID只导出修改过的记录减少数据量和执行时间。配置中心化。从 XML 配置迁移到更完整的配置中心支持在线修改和版本审计。结果元数据化。导出时同时生成一份 JSON 元数据描述导出时间、来源库、查询条件、字段映射方便下游自动解析。与数据看板集成。把导出的材料数据接入 BI 工具或数据中台替代人工定期更新报表。把导出脚本升级成数据订阅服务后通常会遇到权限、增量计算和调度可靠性三个问题。这也是 Granta MI 数据工程化过程中最值得继续投入的方向。