使用Azure Data Factory从Rest API向Azure Synapse表加载数据时随机出现NULL记录

1. 检查API返回的特殊字符或转义问题 #

• 部分记录的字段可能包含不可见控制字符（如换行符、制表符、Unicode控制码），ADF在解析JSON时可能因无法识别而置为NULL。可以在ADF的复制活动中开启日志记录，查看这些NULL记录对应的原始JSON响应内容，确认是否存在此类字符。
• 解决：在复制活动的源设置中，添加JSON路径表达式对字段进行清洗，比如用replace(replace($.fieldName, '\n', ''), '\t', '')去除控制字符；或者在Synapse中执行UPDATE stage_table SET fieldName = REPLACE(REPLACE(fieldName, CHAR(10), ''), CHAR(9), '') WHERE fieldName IS NULL来清洗数据。

2. 验证ADF复制活动的字段映射精度 #

• 即使映射看起来无误，也可能存在大小写不匹配（比如API返回的是FieldName，映射的是fieldname），ADF默认区分大小写，会导致字段无法匹配而置为NULL。
• 解决：在ADF的映射界面，开启大小写不敏感匹配（映射设置的高级选项中），或者手动核对每个字段的名称大小写，确保完全一致。

3. 检查字段长度超限问题 #

• 虽然表定义是nvarchar(4000)，但API返回的字段内容可能实际长度超过4000（注意nvarchar按字符数计算，但部分Unicode字符占2字节，ADF写入时若截断失败可能直接置为NULL）。
• 解决：将表字段临时改为nvarchar(max)，写入后查看这些NULL记录的实际字段长度，再调整表结构为合适的长度；同时在复制活动中开启截断警告，便于及时发现长度超限问题。

4. 排查ADF的JSON解析模式 #

• 如果API返回的是嵌套JSON结构，即使整体结构一致，少数记录可能存在缺失的层级（比如大部分记录是data.field，但个别记录的data为空对象），ADF默认解析时会置为NULL。
• 解决：在复制活动的源设置中，将JSON解析模式改为宽松模式（Relaxed）；或者使用条件表达式处理嵌套字段，比如用coalesce($.data.field, '')替代直接映射$.data.field，避免因层级缺失导致NULL。

5. 检查API分页或分批返回的异常 #

• 部分记录可能来自API的某一页返回，该页响应存在传输异常（比如网络波动导致部分字段丢失），ADF未检测到错误但写入了NULL。
• 解决：在ADF的复制活动中开启逐行验证（验证设置中），当检测到字段为NULL时触发重试；或者手动调用API获取这些异常记录的原始响应，确认是否API本身返回了NULL。

内容的提问来源于stack exchange，提问作者Sandeep T