Azure Synapse连接Blob存储私有容器报错如何解决

根因说明 #

• 原有代码存在认证逻辑适配错误：fs.azure.sas配置项仅支持SAS令牌认证场景，托管身份认证走OAuth2协议，完全不适用这套配置。公共容器无需鉴权即可访问，因此代码能正常运行；访问私有容器时鉴权失败，Spark会抛出「Path does not exist」的误导性报错，并非路径真的不存在。
• 使用账户级SAS链接服务时抛出SasTokenNull错误，是因为链接服务内的SAS配置无效：常见原因包括创建链接服务时选错认证类型、填入的SAS令牌格式错误/已过期/权限范围未覆盖目标容器、IP限制规则拦截了Synapse的访问请求，导致Synapse无法提取到有效SAS令牌。

解决方法 #

方案1：使用托管身份认证（生产环境优先推荐） #

无需获取SAS令牌，直接配置OAuth认证参数即可，步骤如下：

• 提前配置权限：在目标存储账户的访问控制(IAM)页面，给Synapse工作区对应的系统/用户分配托管身份授予存储Blob数据读者（仅读场景）或对应的数据平面操作角色，不要只分配管理平面的存储账户参与者等角色，权限分配后等待5-10分钟生效。如果存储账户开启了防火墙，需要勾选「允许受信任的Microsoft服务访问此存储账户」，同时将Synapse出口IP加入允许列表。
• 替换原有SAS相关的配置代码，参考如下示例：

# 拼接目标文件路径
wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)
# 配置托管身份OAuth认证
spark.conf.set(f"fs.azure.account.auth.type.{blob_account_name}.blob.core.windows.net", "OAuth")
spark.conf.set(f"fs.azure.account.oauth.provider.type.{blob_account_name}.blob.core.windows.net", "org.apache.hadoop.fs.azurebfs.oauth2.MsiTokenProvider")
# 读取文件
df = spark.read.option('multiline','true').json(wasb_path)

提示：通用V2存储也可以直接使用abfss协议替换wasbs，路径格式调整为abfss://<容器名>@<存储账户名>.blob.core.windows.net/<文件相对路径>，整体兼容性更好。

方案2：使用SAS令牌认证 #

如果必须采用SAS认证，按以下步骤修复：

• 重新创建Blob存储链接服务：认证类型明确选择「SAS」，填入的SAS令牌不要带前缀的?符号，提前确认令牌在有效期内、权限覆盖目标容器的读操作、允许访问的IP范围包含Synapse集群出口地址。
• 调整代码逻辑，获取凭证后先校验有效性再配置，参考示例：

# 从链接服务获取凭证
sas_token = mssparkutils.credentials.getConnectionStringOrCreds(linked_service_name)
# 校验凭证非空，避免空值问题
if not sas_token:
    raise Exception("从链接服务获取SAS令牌失败，请检查链接服务配置")
# 拼接路径
wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)
# 配置SAS认证
spark.conf.set(f"fs.azure.sas.{blob_container_name}.{blob_account_name}.blob.core.windows.net", sas_token)
# 读取文件
df = spark.read.option('multiline','true').json(wasb_path)

注意：fs.azure.sas配置项仅接受纯SAS令牌值，不要传入完整存储连接字符串，否则依然会鉴权失败。

额外排查点 #

• 校验路径拼写：确认容器名、存储账户名、文件相对路径没有多余斜杠、大小写错误或特殊字符转义问题
• 权限核验：如果用托管身份，确认角色分配的范围是目标容器/存储账户，而非上级资源组，避免权限不生效

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