连接器¶

Connector 保存外部数据源的地址、认证和连接参数，供载入、查询或导出流程复用。连接配置属于工作区资源，不应在不同环境之间直接复制密钥。

当前 SDK 覆盖范围¶

截至本页核对的官方 moi-python-sdk 与 moi-go-sdk 主分支，公开客户端提供的是 Connector 文件工作流：

上传一个或多个本地文件到 Connector 临时存储；
预览本地上传文件或 Connector URI；
使用已上传文件创建导入；
获取 Connector 文件的签名下载地址；
删除 Connector 临时文件。

两个 SDK 当前都没有公开创建、列出、读取、更新、删除或验证外部 Connector 配置的方法，也没有公开浏览数据库 Schema 的 Connector 方法。请先在 AI Studio 的 数据连接 > 连接器 中创建并测试外部连接，再把已有 Connector 的 ID 或文件 URI 交给 SDK 支持的文件流程。不要自行拼接未公开端点。

控制台支持的数据源类型与字段见连接器参考。

本地文件的暂存与预览¶

Python 的低层客户端可从路径上传一个文件：

upload = client.upload_local_file_from_path(
    "/data/orders.csv",
    [{"filename": "orders.csv", "path": "/"}],
)
conn_file_id = upload["conn_file_ids"][0]

preview = client.preview_connector_file(
    {
        "conn_file_id": conn_file_id,
        "isColumnName": True,
        "columnNameRow": 1,
        "rowStart": 2,
        "file_type": 0,
    }
)

也可以使用 upload_local_file 传入已打开的二进制文件，或用 upload_local_files 一次上传多个文件。meta 不能为空，并应与文件名和目录结构对应。

Go 中对应方法为 UploadLocalFileFromPath、UploadLocalFile、UploadLocalFiles 和 FilePreview：

upload, err := client.UploadLocalFileFromPath(
    ctx,
    "/data/orders.csv",
    []sdk.FileMeta{{Filename: "orders.csv", Path: "/"}},
)
if err != nil {
    return err
}

preview, err := client.FilePreview(ctx, &sdk.FilePreviewRequest{
    ConnFileId: upload.ConnFileIds[0],
})

使用已有外部 Connector 文件预览时，FilePreviewRequest 需要 connector_id，并同时提供 uri 或 conn_file_id。本地暂存文件不传 connector_id，但必须提供 conn_file_id。rowStart 的 SDK 校验范围为 1–1000。

从预览进入导入¶

预览只返回样本和列信息，不会写入 Catalog。调用方需要审查列名、数据类型和表头位置，再构造 TableConfig：

上传或选择 Connector 文件
  → 预览并确认解析参数
  → 决定新建 Table 还是写入已有 Table
  → 配置列映射与冲突策略
  → 调用 upload_connector_file / UploadConnectorFile
  → 保存 task_id 并读取任务状态

具体请求和冲突策略见导入导出。

临时文件生命周期¶

download_connector_file / DownloadConnectorFile 返回签名 URL。导入完成或不再需要时，使用 delete_connector_file / DeleteConnectorFile 删除 conn_file_id 对应的临时文件。

不要把 Connector 临时文件 ID 当作 Catalog File ID。前者服务于上传和导入准备，后者属于 Volume 中的持久资产；两者使用不同的方法。

安全与排错¶

API Key、数据库密码、对象存储密钥不得写入日志或版本库。
连接问题应先在控制台重新运行 测试连接，再检查任务字段。
预览失败时，核对 connector_id 与 uri / conn_file_id 的组合、文件类型、表头行和起始行。
导入失败时保留 SDK 返回的请求标识和 task_id，再读取任务详情。