Synapse管道执行含%run魔法命令的Notebook时路径定位失败求助

问题描述 #

魔法命令在Notebook手动运行时正常，但通过Synapse管道执行同一Notebook时，无法找到目标Notebook路径，报错如下：

{
    "errorCode": "6002",
    "message": "MagicUsageError: Cannot read notebook Externals/Helper. The possible reason is that the notebook doesn't exist. More details please visit https://go.microsoft.com/fwlink/?linkid=2173018\n--> PartnerException: Exception of type 'Microsoft.Analytics.SynapseNotebookService.Infrastructure.Exceptions.ClientExceptions.PartnerException' was thrown.",
    "failureType": "UserError",
    "target": "sample",
    "details": []
}

解决步骤 #

• 修正路径格式：确保魔法命令（如%run）中引用的Notebook使用工作区根目录开头的绝对路径，比如写成%run /Externals/Helper（开头加斜杠）。手动运行时相对路径可识别，但管道执行需严格的绝对路径格式。
• 核对权限设置：管道使用的服务主体/托管标识必须拥有Externals/HelperNotebook的读取权限。手动运行依赖个人账号权限，而管道用的是服务身份，需在Synapse工作区IAM中为该身份添加对应权限。
• 确认Notebook存在性：检查Synapse工作区中Externals文件夹下是否确实存在HelperNotebook，注意路径的大小写和空格——管道执行时会严格匹配，手动运行可能忽略这些细节。
• 检查魔法命令语法：确保%run命令写法正确，不要添加.ipynb后缀，路径不要有多余的空格或特殊字符。

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