GDIM数据对接 (Data Exchange)

本章说明如何为 GDIM 数据对接 应用编写 Pipeline：把项目数据导出为文件，或把外部文件导入到项目。例如导出全部表为 .gtb / .xlsx、导出 GEO5 等第三方软件的格式、把 .gtb / .xlsx 批量写回项目。

应用类型的整体划分见 GDIM应用类型 (App Types)，共用构建步骤见工作流构建 (Pipeline Build)。

两个方向

	导出（GDIM → 文件）	导入（文件 → GDIM）
输入	`GdimTableReader` 读取项目表	用户在前端上传的文件，通过 `file` 属性传入读取模块
输出	文件（`GdimFile`），用户在 GDIM 下载	写入项目表；通常不向前端返回数据
典型模块	`ExportGdimTables`；第三方格式用 `PythonCoder` 转换 + `DocDataWriter` + `ExcelPrinter`；`GeoSectionsWriter` 等文件写出模块	`ReadGtbFile`、`ExcelReader`、`CsvReader`、`MdbReader` + `GdimTableWriter`；需要时 `UpdateGdimAppProjectInfo`
`return_results_config`	文件端口，如 `{"ExportTables": "OutputFile"}`	通常 `False`

导出规则

文件模块设 save_to_gdim = True 。否则文件只留在服务器本地路径，GDIM 拿不到 GdimFile。 ExportGdimTables、ExcelPrinter、GeoSectionsWriter、TextWriter 都是如此。
``return_results_config`` 指向文件端口。 例如 {"ExportTables": "OutputFile"}。
``ExportGdimTables`` 需要模板 ID。 用 GdimAppProjectInfoReader.OutputProjectInfo 接 ExportGdimTables.InputTemplateId。
导出全部表时不设 table_fields 。 GdimTableReader 默认读取项目内所有表及全部字段；希望空表也导出结构时设 empty_error_type = "create_empty_table"。
格式、是否导出空表等选项用属性暴露。 例如 format``（``gtb / xlsx）、export_fields_description。
第三方模板（如 Excel 模板）通过 template 属性提供，不要写死本机路径；上传后由前端传入 GDIM 文件描述。

导出示例

from pathlib import Path

from gdisdk.connectors import log_in
from gdisdk.modules import ExportGdimTables, GdimAppProjectInfoReader, GdimTableReader
from gdisdk.pipeline import PipeLine

_SCRIPT_DIR = Path(__file__).resolve().parent
WORKSPACE_DIR = _SCRIPT_DIR / "workspace"


def build_pipeline() -> PipeLine:
    pipeline = PipeLine(
        app_name="ExportAllTableData",
        app_title="导出所有表数据",
        workspace=WORKSPACE_DIR,
    )
    pipeline.update_gdim_state(token=log_in(), proj_id="你的GDIM项目ID")

    read_tables = GdimTableReader("ReadTables")        # 不设 table_fields：读取全部表
    read_tables.empty_error_type = "create_empty_table"

    read_project_info = GdimAppProjectInfoReader("ReadProjectInfo")

    export_tables = ExportGdimTables("ExportTables")
    export_tables.save_to_gdim = True

    pipeline.add_links(
        read_tables.OutputTables >> export_tables.InputTables
        | read_project_info.OutputProjectInfo >> export_tables.InputTemplateId
    )

    pipeline.add_attribute(
        attr_name="format",
        module_name="ExportTables",
        param_name="format",
        attr_title="导出格式",
    )
    pipeline.add_attribute(
        attr_name="export_fields_description",
        module_name="ExportTables",
        param_name="export_fields_description",
        attr_title="导出字段描述",
    )

    pipeline.return_results_config = {"ExportTables": "OutputFile"}
    pipeline.save_pipeline(f"{pipeline.workspace}/{pipeline.app_name}.pipe")
    return pipeline


if __name__ == "__main__":
    pipeline = build_pipeline()
    pipeline.set_attributes(format="xlsx", export_fields_description=True)
    result = pipeline.run(return_results=pipeline.return_results_config)
    print(result.get_result("ExportTables", "OutputFile"))

本地测试时若不想上传文件到 GDIM，可临时把 save_to_gdim 设为 False，但 保存的 .pipe 里必须是 True。

导入规则

文件通过 file 属性由前端上传。 pipeline.add_attribute(attr_name="file", module_name=..., param_name="file")。平台运行时前端传入 GDIM 文件描述 dict，模块据此下载后读取。不要在 .pipe 里写死本机路径。
写库模块保留在 .pipe 里。导入是「运行即写库」，GdimTableWriter 保持默认 auto_run=True。这一点和 GDIM数据更新 (Data Update) 相反，不要混用两者的规则。
校验模板。 ReadGtbFile.validate_template_id = True，确保文件来自同一数字模型。
写库参数。 批量导入通常设 raise_error = False``（单表失败不中止整体）、``validation_level = "full"、外部来源数据类型不一致时 auto_convert = True。
需要恢复坐标系统时，把 ReadGtbFile.OutputCoordinateSystem 接到 UpdateGdimAppProjectInfo.InputResultModel。
``return_results_config`` 通常设 False。

导入示例

from pathlib import Path

from gdisdk.connectors import log_in
from gdisdk.modules import GdimTableWriter, ReadGtbFile, UpdateGdimAppProjectInfo
from gdisdk.pipeline import PipeLine

_SCRIPT_DIR = Path(__file__).resolve().parent
WORKSPACE_DIR = _SCRIPT_DIR / "workspace"


def build_pipeline() -> PipeLine:
    pipeline = PipeLine(
        app_name="ImportAllTableData",
        app_title="导入所有表数据",
        workspace=WORKSPACE_DIR,
    )
    pipeline.update_gdim_state(token=log_in(), proj_id="你的GDIM项目ID")

    read_gtb = ReadGtbFile("ReadGtbFile")
    read_gtb.validate_template_id = True

    write_tables = GdimTableWriter("WriteGdimTables")
    write_tables.raise_error = False
    write_tables.validation_level = "full"
    write_tables.auto_convert = True

    update_proj_info = UpdateGdimAppProjectInfo("UpdateProjectInfo")

    pipeline.add_links(
        read_gtb.OutputTables >> write_tables.InputData
        | read_gtb.OutputCoordinateSystem >> update_proj_info.InputResultModel
    )

    pipeline.add_attribute(
        attr_name="file",
        module_name="ReadGtbFile",
        param_name="file",
        attr_title="导入文件（.gtb 或 .xlsx）",
    )

    pipeline.return_results_config = False
    pipeline.save_pipeline(f"{pipeline.workspace}/{pipeline.app_name}.pipe")
    return pipeline


if __name__ == "__main__":
    pipeline = build_pipeline()
    pipeline.set_attributes(file=str(WORKSPACE_DIR / "gdim_tables.xlsx"))   # 本地测试文件
    pipeline.run()

第三方格式

目标格式和 GDIM 表结构不一致时（例如 GEO5 的钻孔 / 地层表），在读取和输出之间加一段转换：

GdimTableReader ──► PythonCoder（转换为目标格式的 TableCollection）
                         │
                         ▼
                   DocDataWriter ──► ExcelPrinter（save_to_gdim=True，template 属性）
                                          │ OutputFile ← return_results_config

PythonCoder 的输出端口要声明类型，例如 add_dynamic_ports_out("OutputTables", ptype=PortType.TableCollection)。完整案例见案例十四：平台数据对接GEO5。

常见错误

导出文件没设 save_to_gdim=True 。本地能生成文件，上传后拿不到 GdimFile。
导入文件写死本机路径。 应通过 file 属性由前端上传。
把数据更新的规则用到导入上。 导入应用要在运行时写库，.pipe 里保留 GdimTableWriter。
``ExportGdimTables`` 没接模板 ID。 缺少 GdimAppProjectInfoReader → InputTemplateId 这条线。
``return_results_config`` 指向中间表。 导出应用应只返回文件端口。

与其它文档的关系

导出 / 导入案例：案例十二：导出GDIM表数据、案例十三：将数据导入到GDIM、案例十四：平台数据对接GEO5
ExportGdimTables、GdimTableWriter、ExcelPrinter：modules.writers 模块帮助
ReadGtbFile、ExcelReader、MdbReader：modules.readers 模块帮助
上传前检查：上传GDIM检查 (GDIM Upload Check)