如何通过ADF读取ADLS子文件夹JSON文件按文件名建表摄入ADX

前置准备 #

• 在ADF链接服务中完成两个服务的认证配置：
  • ADLS Gen2链接：授予服务主体/托管身份存储账户的Storage Blob Data Reader权限，确保可列取目录、读取文件内容
  • ADX链接：授予对应服务主体/托管身份目标数据库的Admin（建表需要）、Ingestor（写入数据需要）权限
• 提前确定ADLS遍历的根目录路径，示例场景根目录为/UserData/Overground/UsersFolder/ProjectName/Environment1/data/json/

具体实现步骤 #

1. 初始化管道变量 #

新建管道后，在管道变量面板创建3个变量：

• folderQueue：数组类型，初始值设为根路径组成的单元素数组，即["/UserData/Overground/UsersFolder/ProjectName/Environment1/data/json/"]，用来做广度优先遍历的目录队列
• currentFolder：字符串类型，无初始值，存储当前轮次遍历的目录路径
• jsonFileList：数组类型，无初始值，存储所有遍历到的JSON文件完整路径

2. 递归遍历全量目录与JSON文件 #

单轮Get Metadata活动仅能读取当前目录下的直接子项，无法自动穿透多层嵌套目录，需要搭配Until活动实现递归遍历：

1. 拖入Until活动，设置终止条件为@empty(variables('folderQueue'))，即目录队列为空时停止遍历
2. 在Until活动内部按顺序添加以下活动：
   • 「设置变量」活动1：给currentFolder赋值，取队列头部的路径，表达式为@first(variables('folderQueue'))
   • 「设置变量」活动2：更新目录队列，移除已经取出的头部路径，表达式为@skip(variables('folderQueue'),1)
   • Get Metadata活动：绑定ADLS Gen2数据集，文件路径动态配置为currentFolder变量值，需返回的字段勾选「子项」「项目类型」
   • 第一个ForEach活动：遍历Get Metadata返回的子项列表@activity('Get Metadata当前目录子项').output.childItems，内部添加If条件判断：
     • 判断规则：子项类型为文件夹，即@equals(item().type,'Folder')
     • 条件命中后，执行「追加变量」活动，将拼接完成的子文件夹完整路径（表达式：@concat(variables('currentFolder'), item().name, '/')）追加到folderQueue队列，供后续轮次遍历
   • 第二个ForEach活动：同样遍历Get Metadata返回的子项列表，内部添加If条件判断：
     • 判断规则：子项为后缀是.json的文件，即@and(equals(item().type,'File'), endswith(item().name,'.json'))
     • 条件命中后，执行「追加变量」活动，将拼接完成的JSON文件完整路径（表达式：@concat(variables('currentFolder'), item().name)）追加到jsonFileList列表

注意：如果待遍历文件总量超过10万、目录层级过深，不要用数组变量存储全量文件路径，可在识别到JSON文件时直接触发后续建表、写入逻辑，避免ADF数组变量大小溢出。

3. 逐文件自动建表并摄入数据 #

Until活动执行完成后，jsonFileList会存储所有待处理的JSON文件路径，后续按单文件维度处理：

1. 拖入ForEach活动，遍历对象为jsonFileList数组，可关闭顺序执行，设置并行度为10-20（根据ADX写入吞吐调整，避免触发限流）
2. 在ForEach内部按顺序添加两个活动：
   • 「Azure Data Explorer命令」活动：执行自动建表逻辑，首先动态提取表名：取文件路径最后一段、移除.json后缀，表达式为@replace(last(split(item(), '/')), '.json', '')。执行的Kusto命令如下，ifnotexists语法可避免重复建表报错，中括号包裹表名可兼容文件名带特殊字符的场景：

   .create table ifnotexists ['@{replace(last(split(item(), '/')), '.json', '')}'] (value:string, name:string, timestamp:date)
   

   • 「复制数据」活动：
     • 源端配置：选择ADLS Gen2数据集，文件路径动态绑定当前遍历的文件路径item()，文件格式选JSON，根据实际JSON结构选择解析模式（多行JSON选「一组JSON对象」，数组格式JSON选「JSON对象数组」），列映射手动对齐三个目标字段：value、name、timestamp，时间字段如果是自定义格式可在源端添加表达式转换为标准日期格式
     • 接收器配置：选择ADX数据集，目标表名动态填写之前提取的表名表达式，写入模式选择「追加」，打开ADX原生批量导入优化选项即可

常见问题优化 #

• 若JSON文件字段名与目标Schema不匹配，可在复制活动映射中配置字段重命名，或在ADX侧配置表更新策略自动做字段转换，无需调整ADF遍历逻辑
• 若ADLS侧存在目录限流报错，可给Get Metadata活动配置2-3次重试，重试间隔设为5秒
• 若存在历史已处理文件不需要重复写入，可在遍历到JSON文件时加一层判断，对比ADX侧已存在表的建表时间/文件修改时间，跳过已处理文件

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