1. 概述
1.1 版本
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.0.9 | 新增「XML解析」算子，可以将输入的 XML 数据解析为行列形式的数据 |
| 4.2.5.4 | 「XML解析」算子设置项中： 1）去掉「命名空间」设置项，该设置项说明请参见历史版本文档 2）上游节点为 API 输入且数据未展开为二维表时，源字段默认为 responseBody 3）XML 语句中支持包含一些不合法字符 4）支持自动获取 XML 文件的「命名空间前缀」、「命名空间URL」 5）支持解析非末端节点 6）可批量去除「解析后字段名称」中的空间前缀 7）解决多层拆块问题 8）优化新增删除节点逻辑 |
1.2 应用场景
对于 API、WebService、OData 接口中响应数据返回的 XML 格式数据、来自 XML 文件的数据，用户想要将其解析为行列格式数据，以供后续加工存储。
1.3 功能简介
FineDataLink 支持在「数据转换」中使用「XML解析」算子将 XML 格式数据解析为行列格式数据，以供后续加工存储。
1.4 兼容说明
4.2.5.4 之前版本，非同一层级下的节点同时被选中解析时，会各自生成解析结果，未解析到的字段补 NULL，结果做「UNION」。如下图所示：
情况一：
用户使用多个 XML 解析分层解析数据，并通过其他算子进行拼接，若升级到 4.2.5.4 及之后版本，不会产生兼容性问题。
情况二：
使用一个 XML 解析算子解析后，通过不同的筛选把数据分成两部分，或者使用 SparkSQL 实现其他操作，若升级到 4.2.5.4 及之后版本，会产生兼容性问题，需要调整任务。
2. 功能说明
「XML解析」算子配置界面如下图所示：
2.1 选择源字段
1）下拉列表内容为所有前置字段名。
2）上游节点为 API 输入且数据未展开为二维表时：
4.2.5.4 之前版本，源字段默认为 default。
4.2.5.4 及之后版本，源字段默认为 responseBody。
3）「解析后保留所有上游输出字段」按钮：勾选后，将所有上游输出字段与解析产生的新字段合并输出。
4）4.2.5.4 及之后版本，XML 语句中包含下面所示字符能正常解析不报错；
\u0000-\u0008: ASCII 码 0-8，包括：NUL(空字符)、SOH(标题开始)、STX(正文开始)、ETX(正文结束)、EOT(传输结束)、ENQ(请求)、ACK(确认)、BEL(响铃)、BS(退格)
\u000B: ASCII码11，即 VT(垂直制表符)
\u000C: ASCII码12，即 FF(换页符)
\u000E-\u001F: ASCII码 14-31
2.2 命名空间声明
2.2.1 4.2.5.4 之前版本
详情请参见：历史版本
2.2.2 4.2.5.4 及之后版本
| 前提条件 | 说明 |
|---|---|
| 选择源字段后&&XML 文件格式正确&&XML 文件中有命名空间 | 自动获取 XML 文件的「命名空间前缀」、「命名空间URL」 |
| 选择源字段后&&XML 文件格式正确&&XML 文件中无命名空间 | 提示没有命名空间 |
「命名空间前缀」、「命名空间URL」说明如下表所示：
| 字段名 | 说明 |
|---|---|
| 命名空间前缀 | 1）支持修改、重新获取（4.2.5.4 及之后版本支持；点击后，先清空已有内容，再重新获取）、新增和删除操作；修改时，需注意：命名空间前缀将影响相关XML节点的XPath路径，请谨慎修改 2）若获取到的命名空间无前缀，则给默认值default、default1、default2......进行命名 3）不允许重名，不能为空 |
| 命名空间URL | 1）支持修改、重新获取（4.2.5.4 及之后版本支持；点击后，先清空已有内容，再重新获取）、新增和删除操作 2）允许重复 |
2.3 解析 XML 数据
2.3.1 选择 XML 节点
点击「选择XML节点」按钮后，弹出XML节点选择框。
数组节点说明：同一层级的多个标签，因同名而被聚合成一个节点，解析后会有多行数据。
| 包含数组的 XML 示例数据： |
|
4.2.5.4 之前版本：
只能选择末端节点，非末端节点不能选中。详细说明请参见：历史版本
4.2.5.4 及之后版本：
| 场景 | 说明 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 选择节点 | 1）支持选择非末端节点和末端节点（末端节点定义：没有子节点；下图黄色字段为末端节点，剩下的字段为非末端节点）
2）选中非末端节点后，对应字段以字符串形式取节点内部 XML 示例：选 xml 节点时选择 friendlist 生成的 XPath 需要是红框部分的路径，字段对应值为红框部分的字符串形式
3）支持同时选中：
不支持同时选中： 已选某数组节点或其子节点，则不能选择其他数组或其他子节点
| ||||||||||||
| 选择的不是同一层的 XML 节点时 | 数据预览和实际运行时，对数据进行拼行处理
| ||||||||||||
| 「解析后字段名称」已存在，再次点击「选择XML节点」按钮时 | 新选择的节点按弹窗中的顺序在原本已有字段的下方添加，如果弹窗中取消选择了已有节点，从原本已有节点中删除 |
2.3.2 输出字段
列表项允许新增、删除、清空（4.2.5.4 及之后版本）。
经过 XML 解析产生的字段类型统一为字符串（从上游带来的字段类型不变）。
| 字段名 | 说明 |
|---|---|
| 解析后字段名称 | 可编辑；配置解析后的字段名称 注1：字段名称不允许重名 注2：不允许引用参数 |
| XPath 路径 | 1）可编辑；展示&配置解析后字段的 XPath 路径表达式 2）不允许引用参数 3）若需解析「选择XML节点」无法生成的路径，可点击「添加字段」按钮并手动填写 XPath 路径 |
| 去除字段名的命名空间前缀 | 点击
去除逻辑： 1）识别命名空间前缀（前缀必须在命名空间声明里出现） 2）如果清除命名空间前缀会导致字段名重复，则保留原本的前缀不去除 |
手写 XPath 支持的类型：「选取节点」类和「谓语」类
例如 XML 文档如下：
<?xml version="1.0" encoding="ISO-8859-1"?>
<bookstore>
<book>
<title lang="eng">Harry Potter</title>
<price>29.99</price>
</book>
<book>
<title lang="eng">Learning XML</title>
<price>39.95</price>
</book>
</bookstore>
选取节点
XPath 使用路径表达式在 XML 文档中选取节点。节点是通过沿着路径或者 step 来选取的。
在下面的表格中，我们已列出了一些路径表达式以及表达式的结果：
| 路径表达式 | 结果 |
|---|---|
| bookstore | 选取 bookstore 元素的所有子节点。 |
| /bookstore | 选取根元素 bookstore。 注：假如路径起始于正斜杠( / )，则此路径始终代表到某元素的绝对路径。 |
| bookstore/book | 选取属于 bookstore 的子元素的所有 book 元素。 |
| //book | 选取所有 book 子元素，而不管它们在文档中的位置。 |
| bookstore//book | 选择属于 bookstore 元素的后代的所有 book 元素，而不管它们位于 bookstore 之下的什么位置。 |
| //@lang | 选取名为 lang 的所有属性。 |
谓语
谓语用来查找某个特定的节点或者包含某个指定的值的节点。
谓语被嵌在方括号中。
在下面的表格中，我们列出了带有谓语的一些路径表达式，以及表达式的结果：
| 路径表达式 | 结果 |
|---|---|
| /bookstore/book[1] | 选取属于 bookstore 子元素的第一个 book 元素 |
| /bookstore/book[last()] | 选取属于 bookstore 子元素的最后一个 book 元素 |
| /bookstore/book[last()-1] | 选取属于 bookstore 子元素的倒数第二个 book 元素 |
| /bookstore/book[position()<3] | 选取最前面的两个属于 bookstore 元素的子元素的 book 元素 |
| //title[@lang] | 选取所有拥有名为 lang 的属性的 title 元素 |
| //title[@lang='eng'] | 选取所有 title 元素，且这些元素拥有值为 eng 的 lang 属性 |
| /bookstore/book[price>35.00] | 选取 bookstore 元素的所有 book 元素，且其中的 price 元素的值须大于 35.00 |
| /bookstore/book[price>35.00]/title | 选取 bookstore 元素中的 book 元素的所有 title 元素，且其中的 price 元素的值须大于 35.00 |
3. 特殊场景处理策略
| 场景 | 处理策略 |
|---|---|
源XML数据存在多个根元素，举例：
| 点击「选择XML节点」时报错：XML数据根节点缺失 自行写XPath，预览及运行时报错：XML数据根节点缺失 |
| 配置的XPath不正确 | 解析出的字段内容为空 |
配置的XPath非法 或者 命名空间前缀中填写了非英文字母的字符 | 抛出解析异常 |
命名空间前缀重复
| 命名空间前缀不可重复 此例中，将两个 s 中的一个重命名为其他名称，并正常填写对应 URI ，通过树选的形式可正常解析 如果是手填路径，需要按照重命名后的命名空间前缀书写路径 |
源XML数据不完整，举例：
| 点击选择XML节点时报错：XML数据格式不完整 自行写XPath，预览及运行时报错：XML数据格式不完整 |
