如何在本地批量转换Git仓库中Azure Synapse JSON格式笔记本至Jupyter/Python

一、官方命令行工具：Synapse CLI #

• 前置准备：先安装Azure CLI，再执行 az extension add --name synapse 安装Synapse扩展
• 单文件转换：完成az login身份验证后，执行以下命令将指定Synapse JSON笔记本导出为ipynb格式：

  az synapse notebook export --workspace-name <你的工作区名称> --name <笔记本名称> --output-folder <本地输出路径> --output-format ipynb
  

• 批量转换：结合Shell/PowerShell脚本遍历Git仓库中的JSON文件，循环执行上述命令即可实现批量处理。

二、Python脚本批量转换 #

如果不想依赖CLI，可直接解析Synapse JSON结构手动转换：
Synapse JSON笔记本的cells字段包含所有单元格内容，source字段对应单元格的代码/文本，cell_type匹配Jupyter的单元格类型（code/markdown等）。

示例转换脚本：

import json
import os

def synapse_to_ipynb(json_path, output_path):
    with open(json_path, 'r', encoding='utf-8') as f:
        synapse_data = json.load(f)
    
    ipynb_template = {
        "cells": [],
        "metadata": {},
        "nbformat": 4,
        "nbformat_minor": 5
    }

    for cell in synapse_data.get('cells', []):
        ipynb_cell = {
            "cell_type": cell.get('cell_type', 'code'),
            "metadata": {},
            "source": cell.get('source', [])
        }
        ipynb_template['cells'].append(ipynb_cell)
    
    with open(output_path, 'w', encoding='utf-8') as f:
        json.dump(ipynb_template, f, indent=2)

# 批量处理逻辑
input_dir = "./synapse_notebooks"  # Git仓库中JSON文件目录
output_dir = "./converted_ipynb"
os.makedirs(output_dir, exist_ok=True)

for file in os.listdir(input_dir):
    if file.endswith(".json"):
        input_path = os.path.join(input_dir, file)
        output_path = os.path.join(output_dir, file.replace(".json", ".ipynb"))
        synapse_to_ipynb(input_path, output_path)
        print(f"转换完成：{file}")

• 转纯Python文件：只需筛选cell_type为code的单元格，将source内容拼接后写入.py文件即可。

三、Git钩子自动化同步 #

若需在Git仓库中自动完成转换，可配置pre-commit钩子：

1. 在仓库.git/hooks目录下创建pre-commit文件
2. 写入上述转换脚本的调用逻辑，确保每次提交Synapse JSON文件时，自动生成对应的ipynb/Python文件并纳入提交

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