Synapse Studio 故障排除

此故障排除指南提供了有关开具网络连接问题的支持票证时提供哪些信息的说明。 有了正确的信息，我们就可以更快地解决问题。

在某些情况下，如果浏览器会话长时间处于非活动状态，则尝试发布可能会因为有关令牌过期的消息而失败：

ERROR: Unauthorized Inner error code: ExpiredAuthenticationToken Message: Token Authentication failed with SecurityTokenExpiredException - MISE12034: AuthenticationTicketProvider Name:AuthenticationTicketProvider, GetVersion:1.9.2.0.;

在 Synapse Studio 中处理令牌过期需要仔细考虑。 以下是如何管理会话以避免丢失工作的方法：

• 在中断或处于非活动状态的时间段之前，请尝试发布更改。 请务必记住，如果会话长时间处于空闲状态，若尝试在返回时发布令牌过期错误，可能会遇到令牌过期错误。
• 如果担心因需要刷新而可能丢失未保存的更改，可考虑在工作时间段内频繁执行保存和发布操作，并避免让会话长时间处于闲置状态。

“无服务器 SQL 池”选项在“连接到”下拉列表中灰显。

使用“无服务器 SQL 池”运行查询会出现“无法建立与服务器的连接”这一错误消息。

打开“诊断信息”面板，选择“下载诊断”按钮。 保留下载的信息用于报告错误。 可以复制“会话 ID”，并在开具支持票证时附加该 ID。

若要开始进行故障排除，请重试你在 Synapse Studio 中执行的操作。

• 对于症状 1，请在“SQL 脚本”选项卡中选择“刷新”按钮，并检查是否可以看到“无服务器 SQL 池”。
• 对于症状 2，请尝试再次运行查询以查看其是否成功执行。

如果问题仍然存在，请在浏览器中按 F12 打开“开发人员工具”(DevTools)。

在“开发人员工具”窗口中，切换到“网络”面板。 如有必要，请在“网络”面板中选择工具栏上的“清除”按钮。

确保已选中“网络”面板中的“禁用缓存”。

重试在 Azure Synapse Studio 中执行的操作。 你可能会在“开发人员工具”的“网络”列表中看到新的项。 请注意当前系统时间以在支持票证中提供。

查找其 URL 列与以下模式匹配的项：

https://[*A*]-ondemand.database.chinacloudapi.cn:1443/databases/[*B*]/query?api-version=2018-08-01-preview&application=ArcadiaSqlOnDemandExplorer

其中 *A* 是工作区名称，-ondemand 可以是 -sqlod，*B* 应是数据库名称，例如 master。 最多应有两个具有相同 URL 值但方法值不同的项；OPTIONS 和 POST。 检查这两项在状态列下是否有 200 或 20x，其中 x 可以是任意一位数字。

如果其中任何一个不是 20x 并且：

• 状态以“（失败）”开头，可以加宽“状态”列，或将指针悬停在状态文本上以查看完整文本。 开具支持票证时，应包含文本和/或屏幕截图。

  

  • 如果看到 ERR_NAME_NOT_RESOLVED，并且在 10 分钟内创建了工作区，请等待 10 分钟，然后重试以查看问题是否仍然存在。
  • 如果看到 ERR_INTERNET_DISCONNECTED 或 ERR_NETWORK_CHANGED，则表明电脑网络连接有问题。 请检查你的网络连接，然后重试该操作。
  • 如果看到 ERR_CONNECTION_RESET，ERR_SSL_PROTOCOL_ERROR 或其他包含“SSL”的错误代码，则表明你的本地 SSL 配置有问题，或者你的网络管理员已阻止对无服务器 SQL 池服务器的访问。 开具支持票证并在描述中附上错误代码。
  • 如果看到ERR_NETWORK_ACCESS_DENIED，则可能需要与管理员核实本地防火墙策略是否阻止了对 *.database.chinacloudapi.cn 域或远程端口 1443 的访问。
  • （可选）立即在另一台计算机和/或不同网络环境上尝试相同的操作，以排除电脑上的网络配置问题。

• 状态为 40x、50x 或其他数字，选择项以查看详细信息。 应会在右侧看到项详细信息。 找到“响应头”部分；然后检查是否存在名为“access-control-allow-origin”的项目。 如果存在，请检查它是否具有以下值之一：

  • *（单个星号）
  • https://web.azuresynapse.azure.cn/（或浏览器地址栏中的文本开头的其他值）

如果响应头包含上述值之一，则意味着应已收集失败信息。 你可以根据需要开具支持票证，并可以选择附加项详细信息的屏幕截图。

如果看不到标头，或者标头没有上述值之一，请在开具票证时附加项详细信息的屏幕截图。

如果上述步骤未能解决问题，可能需要开具支持票证。 提交支持票证时，请包含在本指南开头下载的“会话 ID”或“诊断信息”。

报告问题时，可以选择在“开发人员工具”中截取“控制台”选项卡的屏幕截图，并将其附加到支持票证上。 滚动内容，并在需要时截取多个屏幕截图以捕获整个消息。

如果要附加屏幕截图，请提供截取屏幕截图的时间（或估计的时间范围）。 这将有助于我们调查问题。

某些浏览器支持在“控制台”选项卡中显示时间戳。对于 Chromium Edge/Chrome，请在“开发人员工具”中打开“设置”对话框，然后在“首选项”选项卡中选中“显示时间戳”。

错误消息显示：Your notebook connection has closed unexpectedly. To re-establish the connection, run the notebook again. Diagnostic information: websocket_close_error (correlation id)

笔记本执行依赖于建立到以下 URL 的 WebSocket 连接

wss://{workspace}.dev.azuresynapse.azure.cn/jupyterApi/versions/1/sparkPools/{spark-pool}/api/kernels/{kernel-id}/channels 

• {workspace} 是 Synapse 工作区的名称
• {spark-pool} 是当前正在使用的 Spark 池的名称
• {kernel-id} 是用于区分笔记本会话的 GUID

设置 WebSocket 连接时，Synapse Studio 将在 WebSocket 请求的 Sec-WebSocket-Protocol 标头中包含访问令牌（Microsoft Entra JWT 持有者令牌）。

有时，WebSocket 请求可能被阻止，请求标头中的 JWT 令牌也有可能在你的网络环境中被修订。 这将导致 Synapse Notebook 无法与我们的服务器建立连接并运行你的笔记本。

如果可能，请尝试切换网络环境，例如公司内网/外网，或在另一台工作站上访问 Synapse Notebook。

• 如果可以在同一工作站但在不同的网络环境中运行笔记本，请与网络管理员一起查明 WebSocket 连接是否已被阻止。

• 如果可以在不同工作站但在相同的网络环境中运行笔记本，请确保未安装任何可能阻止 WebSocket 请求的浏览器插件。

否则，请联系网络管理员并确保允许使用以下 URL 模式的出站 WebSocket 请求，并且其请求头未经修订：wss://{workspace}.dev.azuresynapse.azure.cn/{path}

• {workspace} 是 Synapse 工作区名称
• {path} 指示 URI 中的任何子路径（例如，包含斜杠字符）

此 URL 模式比“根本原因”一节中所示的更松散，因为它允许我们向 Synapse 添加新的 WebSocket 相关功能，而不会在将来出现任何潜在的连接问题。

如果将包含 256 个以上代码单元的笔记本添加到管道，管道运行将失败并显示错误代码 6002 和错误消息：MessageQueueFullException: The message queue is full or is completed and cannot accept more items.

从管道执行 Synapse 笔记本活动时，单元格的限制为 256。

可以合并单元格以将单元格数量减少到 256 个以下。

如果前面的步骤不能帮助你解决问题，请创建支持票证