外部同步 API 参考

信息

本文面向实现外部同步接口的开发和集成人员，定义分页请求、链路模型、节点和连线约束，以及接口到服务的下钻绑定。首次配置同步任务，请先完成同步外部业务链路。

前提条件

已在第三方系统中提供可供 ONE 平台访问的 HTTP API。
已为 ONE 平台配置外部数据同步地址；如需鉴权，请按部署环境约定完成网络和鉴权配置。
已为每条链路和每个节点分配稳定、可重复使用的唯一标识。相同对象在不同批次中必须返回相同标识。
需要从接口链路下钻到服务子图时，已准备成对的 interface 链路、service 链路及 relationBindings 数据。

API 请求协议

请求方式

POST /api/topology/list HTTP/1.1
Content-Type: application/json

接口路径 /api/topology/list 为协议示例。实际路径以数据源配置中填写的地址为准。

请求体

{
  "pageNo": 1,
  "pageSize": 1000,
  "uniqueTopologys": ["APPRegist-interface", "APPRegist-service"],
  "topologyName": "APP"
}

字段	类型	是否必填	说明
`pageNo`	Integer	否	页码，从 `1` 开始，默认值为 `1`。
`pageSize`	Integer	否	每页返回的链路条数。建议支持 `1000`，ONE 平台预览和同步通常按每页 `1000` 条拉取。
`uniqueTopologys`	String[]	否	按链路外部 ID 精确过滤。传空数组、`null` 或不传时表示不过滤。
`topologyName`	String	否	按链路名称模糊过滤。

API 响应协议

响应体结构

{
  "code": "200",
  "msg": "success",
  "data": {
    "totalRecord": 40000,
    "pageNo": 1,
    "pageSize": 1000,
    "results": []
  }
}

字段	类型	是否必填	说明
`code`	String	是	响应状态码。`"200"` 表示成功。
`msg`	String	是	响应提示信息。成功时可返回 `"success"`。
`data`	Object	是	分页数据对象。
`data.totalRecord`	long	是	过滤后的链路总数。interface 和 service 链路分别计为一条。
`data.pageNo`	int	是	当前页码，应与请求页码一致。
`data.pageSize`	int	是	当前页大小。
`data.results`	TopologyItem[]	是	当前页的链路列表；无数据时返回 `[]`。

链路 TopologyItem

data.results 中的每个元素表示一条可独立同步的链路。

字段	类型	是否必填	说明
`uniqueTopology`	String	是	链路外部 ID，必须全局唯一且保持稳定，例如 `APPRegist-interface`。
`topologyName`	String	是	链路在 ONE 平台中的展示名称。
`updateTime`	String	是	源端变更时间。无法提供可靠变更时间时，固定返回空字符串 `""`，确保平台每次都读取并比较源端数据。
`nodes`	NodeItem[]	是	链路节点列表；无节点时返回 `[]`。
`edges`	EdgeItem[]	是	链路连线列表；无连线时返回 `[]`。每条连线必须包含完整四元组。
`relationBindings`	RelationBindingItem[]	是	接口节点到服务子图的绑定关系。无绑定时必须返回 `[]`，不能传 `null` 或省略该字段。

节点 NodeItem

字段	类型	是否必填	说明
`uniqueNode`	String	是	节点在相同 `nodeType` 下的外部唯一标识。必须按下方 CMDB 实例唯一规则构造，平台使用该标识关联查询实例并获取实例 ID。允许包含竖线 `\|`。
`nodeName`	String	是	节点展示名称。
`nodeType`	String	是	节点对应的 ONE 平台 `modelKey`，例如 `interface`、`service`。禁止包含竖线 `\|`。

节点的实际唯一性由 nodeType 和 uniqueNode 共同确定。因此，不同类型的节点可以使用相同的 uniqueNode。

`uniqueNode` 与 CMDB 实例关联规则

平台根据 nodeType 确定对应的 CMDB 实体模型，再使用 uniqueNode 按该模型的实例唯一规则查询实例；匹配成功后，平台获取并关联该 CMDB 实例的实例 ID。

实体模型	`uniqueNode` 默认构造规则	默认唯一标识说明
服务（`service`）	`${detectedName}`	服务识别名称。
接口（`interface`）	`${detectedName}_${interfaceType}_${service.detectedName}`	接口识别名称 + 接口类型 + 所属服务 ID。

注意

表中为服务和接口模型的默认实例唯一规则。uniqueNode 不能使用与 CMDB 实例无关的任意业务 ID；如果平台中的 CMDB 模型已经调整唯一规则，请按实际配置构造。字段值、大小写和下划线分隔方式必须保持一致，否则平台无法关联实例或获取实例 ID。

连线 EdgeItem

字段	类型	是否必填	说明
`fromNodeType`	String	是	起点节点类型，必须与起点节点的 `nodeType` 一致。
`fromUniqueNode`	String	是	起点节点唯一标识，必须能在本链路 `nodes` 中找到。
`toNodeType`	String	是	终点节点类型，必须与终点节点的 `nodeType` 一致。
`toUniqueNode`	String	是	终点节点唯一标识，必须能在本链路 `nodes` 中找到。

注意

连线必须同时提供 fromNodeType、fromUniqueNode、toNodeType 和 toUniqueNode。仅提供起止节点 ID 的历史二元组格式会被丢弃，导致同步后的链路缺少连线。

下钻绑定 RelationBindingItem

relationBindings 用于描述“interface 链路中的某个接口节点，可以下钻查看 service 链路中的哪些节点和连线”。

字段	类型	是否必填	说明
`sourceUniqueTopology`	String	是	下钻入口所在的 interface 链路 ID。
`sourceNodeType`	String	是	下钻入口节点类型，接口场景填写 `interface`；禁止包含竖线 `\|`。
`sourceUniqueNode`	String	是	下钻入口节点的 `uniqueNode`，必须与对应 interface 链路中的节点一致。
`associatedNodes`	NodeRefItem[]	是	service 链路中与该接口关联的节点引用列表；无关联节点时返回 `[]`。
`associatedEdges`	EdgeItem[]	是	service 链路中与该接口关联的连线列表；无关联连线时返回 `[]`。

associatedNodes 中的每个节点引用使用以下结构：

字段	类型	是否必填	说明
`nodeType`	String	是	关联节点类型，例如 `service`。
`uniqueNode`	String	是	关联节点在 service 链路中的唯一标识。

注意

associatedNodes 必须是对象数组，例如 [{"nodeType":"service","uniqueNode":"node-A"}]。请勿使用 ["node-A"] 形式的字符串数组，否则可能导致反序列化失败或绑定数据为空。

完整 JSON 示例

以下示例返回同一业务功能对应的 interface 链路和 service 链路，并将 interface 节点 W12001214 绑定到 service 子图。用户在 interface 链路中选择该节点后，可以继续下钻查看绑定的服务节点和连线。

{
  "code": "200",
  "msg": "success",
  "data": {
    "totalRecord": 40000,
    "pageNo": 1,
    "pageSize": 1000,
    "results": [
      {
        "uniqueTopology": "APPRegist-interface",
        "topologyName": "注册（手机号登录）-功能号拓扑",
        "updateTime": "",
        "nodes": [
          {
            "uniqueNode": "APPRegist",
            "nodeName": "注册（手机号登录）",
            "nodeType": "interface"
          },
          {
            "uniqueNode": "W12001214",
            "nodeName": "君弘手机号校验激活",
            "nodeType": "interface"
          }
        ],
        "edges": [
          {
            "fromNodeType": "interface",
            "fromUniqueNode": "APPRegist",
            "toNodeType": "interface",
            "toUniqueNode": "W12001214"
          }
        ],
        "relationBindings": []
      },
      {
        "uniqueTopology": "APPRegist-service",
        "topologyName": "注册（手机号登录）-组件拓扑",
        "updateTime": "",
        "nodes": [
          {
            "uniqueNode": "node11723473851691",
            "nodeName": "node11723473851691",
            "nodeType": "service"
          },
          {
            "uniqueNode": "node01636960691574",
            "nodeName": "node01636960691574",
            "nodeType": "service"
          }
        ],
        "edges": [
          {
            "fromNodeType": "service",
            "fromUniqueNode": "node11723473851691",
            "toNodeType": "service",
            "toUniqueNode": "node01636960691574"
          }
        ],
        "relationBindings": [
          {
            "sourceUniqueTopology": "APPRegist-interface",
            "sourceNodeType": "interface",
            "sourceUniqueNode": "W12001214",
            "associatedNodes": [
              {
                "nodeType": "service",
                "uniqueNode": "node11723473851691"
              },
              {
                "nodeType": "service",
                "uniqueNode": "node01636960691574"
              }
            ],
            "associatedEdges": [
              {
                "fromNodeType": "service",
                "fromUniqueNode": "node11723473851691",
                "toNodeType": "service",
                "toUniqueNode": "node01636960691574"
              }
            ]
          }
        ]
      }
    ]
  }
}

请遵循以下配对规则：

interface 链路的 relationBindings 始终返回 []。
service 链路通过 relationBindings 描述 interface 节点到 service 子图的下钻关系。
同一 service 链路可以包含多条 binding，分别对应不同的 interface 节点。
associatedNodes 和 associatedEdges 只引用当前 service 链路 nodes 和 edges 中已经存在的数据。
API 分别返回 nodeType 和 uniqueNode，不要在 uniqueNode 中主动拼接 service|、interface| 等内部复合键。

常见数据场景

service 子图只有并列节点

当多个 service 节点之间没有明确的前后调用关系时，可以只返回关联节点，不返回连线。

{
  "uniqueTopology": "APPRegist-service",
  "topologyName": "注册（手机号登录）-组件拓扑",
  "updateTime": "",
  "nodes": [
    {
      "uniqueNode": "node11723473851691",
      "nodeName": "node11723473851691",
      "nodeType": "service"
    },
    {
      "uniqueNode": "node01636960691574",
      "nodeName": "node01636960691574",
      "nodeType": "service"
    }
  ],
  "edges": [],
  "relationBindings": [
    {
      "sourceUniqueTopology": "APPRegist-interface",
      "sourceNodeType": "interface",
      "sourceUniqueNode": "W12001214",
      "associatedNodes": [
        {
          "nodeType": "service",
          "uniqueNode": "node11723473851691"
        },
        {
          "nodeType": "service",
          "uniqueNode": "node01636960691574"
        }
      ],
      "associatedEdges": []
    }
  ]
}

`uniqueNode` 包含竖线

uniqueNode 可以包含 \|，例如 svc|node-A；nodeType 不能包含 \|。平台只将 nodeType 与完整的 uniqueNode 组合为内部键，不会把 uniqueNode 中的竖线误认为类型分隔符。

{
  "uniqueTopology": "PAY|001-service",
  "topologyName": "支付链路-组件拓扑",
  "updateTime": "",
  "nodes": [
    {
      "uniqueNode": "svc|node-A",
      "nodeName": "支付服务A",
      "nodeType": "service"
    }
  ],
  "edges": [],
  "relationBindings": []
}

不同类型使用相同节点 ID

同一条链路中，service 节点和 interface 节点可以使用相同的 uniqueNode。平台使用 nodeType + uniqueNode 识别节点，两者不会发生冲突。

{
  "uniqueTopology": "Order-service",
  "topologyName": "订单-组件拓扑",
  "updateTime": "",
  "nodes": [
    {
      "uniqueNode": "pay",
      "nodeName": "支付组件",
      "nodeType": "service"
    },
    {
      "uniqueNode": "pay",
      "nodeName": "支付接口",
      "nodeType": "interface"
    }
  ],
  "edges": [],
  "relationBindings": []
}

一个 service 链路绑定多个 interface 节点

当同一条 service 链路需要从多个 interface 节点下钻进入时，为每个 interface 节点分别添加一条 binding。每条 binding 可以关联不同的 service 子图。

{
  "uniqueTopology": "APPRegist-service",
  "topologyName": "注册-组件拓扑",
  "updateTime": "",
  "nodes": [
    {
      "uniqueNode": "node-A",
      "nodeName": "node-A",
      "nodeType": "service"
    },
    {
      "uniqueNode": "node-B",
      "nodeName": "node-B",
      "nodeType": "service"
    },
    {
      "uniqueNode": "node-C",
      "nodeName": "node-C",
      "nodeType": "service"
    }
  ],
  "edges": [
    {
      "fromNodeType": "service",
      "fromUniqueNode": "node-A",
      "toNodeType": "service",
      "toUniqueNode": "node-B"
    }
  ],
  "relationBindings": [
    {
      "sourceUniqueTopology": "APPRegist-interface",
      "sourceNodeType": "interface",
      "sourceUniqueNode": "W12001214",
      "associatedNodes": [
        {
          "nodeType": "service",
          "uniqueNode": "node-A"
        },
        {
          "nodeType": "service",
          "uniqueNode": "node-B"
        }
      ],
      "associatedEdges": [
        {
          "fromNodeType": "service",
          "fromUniqueNode": "node-A",
          "toNodeType": "service",
          "toUniqueNode": "node-B"
        }
      ]
    },
    {
      "sourceUniqueTopology": "APPRegist-interface",
      "sourceNodeType": "interface",
      "sourceUniqueNode": "W12001215",
      "associatedNodes": [
        {
          "nodeType": "service",
          "uniqueNode": "node-C"
        }
      ],
      "associatedEdges": []
    }
  ]
}

数据校验规则

ONE 平台在应用同步数据前校验 relationBindings。请在联调时优先检查以下规则：

编号	校验规则	不符合规则时的结果
C1	`associatedNodes` 中的每个节点必须存在于当前 service 链路的 `nodes` 中。	无效节点引用会被丢弃并记录警告；应用校验失败时，当前链路进入失败列表。
C2	`associatedEdges` 中的每条连线必须存在于当前 service 链路的 `edges` 中，且四元组完全一致。	无效连线会被丢弃并记录警告；应用校验失败时，当前链路进入失败列表。
C3	`sourceNodeType` 不能包含 `\|`。	整条 binding 会被丢弃并记录警告。
C4	`sourceUniqueNode` 必须与 `sourceUniqueTopology` 对应 interface 链路中的节点一致。	下钻入口会错位，无法正确展示 service 子图。

不兼容格式

不兼容场景	错误数据示例	同步结果
连线缺少节点类型	只返回 `fromUniqueNode`、`toUniqueNode`	该连线被丢弃，链路结构可能不完整。
关联节点使用字符串数组	`"associatedNodes": ["node-A"]`	可能反序列化失败或无法生成绑定关系。
binding 缺少 `sourceNodeType`	省略该字段	整条 binding 被丢弃。
节点或连线重复	同一节点引用或四元组重复出现	平台去重并记录警告，保留一条有效数据。
连线端点不存在	连线引用了 `nodes` 中不存在的节点	该连线被丢弃，链路结构可能不完整。

联调检查清单

在执行正式同步前，建议使用一组少量数据逐项检查：

确认成功响应中的 code 为字符串 "200"，分页信息与当前请求一致。
确认 totalRecord 是过滤后的链路总数，而不是当前页数量或业务功能数量。
确认所有列表字段在无数据时返回 []，尤其是 nodes、edges 和 relationBindings。
确认每个 uniqueNode 均按对应 CMDB 模型的实例唯一规则构造，并能关联查询到实例 ID。
确认每条边的四个字段齐全，且起止节点都能在当前链路中找到。
确认 interface 和 service 链路使用不同且稳定的 uniqueTopology。
确认每个 binding 的关联节点和关联边都属于当前 service 链路。
确认分页顺序和数据在一次同步期间保持稳定，避免重复或遗漏链路。

提示

首次联调时，可通过 uniqueTopologys 只返回一组 interface/service 配对链路。确认节点、连线和下钻关系正确后，再扩大同步范围。

注意

外部数据同步可能耗时较长，请等待当前任务完成后再发起下一次同步。
同步期间请勿离开当前页面或刷新浏览器，以免同步失败。
每个账号同一时间只能执行一个同步任务。
无法提供可靠 updateTime 时请固定返回空字符串，不要返回会随请求时间变化的当前时间。

前提条件​

API 请求协议​

请求方式​

请求体​

API 响应协议​

响应体结构​

链路 TopologyItem​

节点 NodeItem​

uniqueNode 与 CMDB 实例关联规则​

连线 EdgeItem​

下钻绑定 RelationBindingItem​

完整 JSON 示例​

常见数据场景​

service 子图只有并列节点​

uniqueNode 包含竖线​

不同类型使用相同节点 ID​

一个 service 链路绑定多个 interface 节点​

数据校验规则​

不兼容格式​

联调检查清单​