问题描述

在APIM的API操作页面，为了备份API的所有配置信息，先使用导出功能把API导出为OpenAPI(YAML)文件。

但诡异的是，紧接着把同样的文件导入时，却报错：Unable to parse specified file. Please ensure it is valid OpenAPI specification document.

当根据常规排查思路，打开浏览器开发者模式(F12)，查看是否有Console Error，是否有Network Trace错误？

通过浏览器开发者工具（Console / Network）确认：

前端未抛出 JS 异常
后端未返回结构化错误信息

这基本可以判断：问题不在 Portal 前端逻辑，而更可能发生在服务端对文件内容的解析阶段。

导入报错截图：

面对这个问题，应该如何排查呢？

问题解答

这个问题，最让人迷惑的行为时：文件有API的导出功能生成，而马上用于导入时候，确报错说不是有效的OpenAPI文件格式。

于是，怀疑是APIM的门户出现了Bug。为了绕过 Portal 的前端封装，直接验证 APIM 后端对 OpenAPI 文件的解析行为，使用 Azure CLI 进行 API 导入测试。

此处使用了az apim api import命令，来交叉验证问题。

执行命令：
> az apim api import -g <group name> --service-name <apim anme>  --path apiimport03  --specification-path .\API.openapi.yaml  --specification-format OpenApi

返回结果：
The command failed with an unexpected error. Here is the traceback:
'charmap' codec can't decode byte 0x81 in position 1463: character maps to <undefined>
Traceback (most recent call last):
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\knack/cli.py", line 233, in invoke
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/commands/__init__.py", line 666, in execute
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/commands/__init__.py", line 734, in _run_jobs_serially
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/commands/__init__.py", line 703, in _run_job
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/commands/__init__.py", line 336, in __call__
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/commands/command_operation.py", line 120, in handler
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/command_modules/apim/custom.py", line 450, in apim_api_import
  File "encodings\cp1252.py", line 23, in decode
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 1463: character maps to <undefined>
To check existing issues, please visit: https://github.com/Azure/azure-cli/issues

这次错误的信息非常明显：

'charmap' codec can't decode byte 0x81 in position 1463: character maps to

'charmap' 编解码器无法解码位置 1463 处的字节 0x81：字符映射到 <未定义>

0x81 是一个在 UTF-8 / Windows-1252 / GBK 中都不合法或语义不一致的字节，通常意味着：

文件实际为 UTF-8，但被当作 ANSI/GBK 解码
或拷贝/导出过程中发生了编码污染

当看见这类消息后，确实开始怀疑是否有特殊编码字符导致文件格式不对。

于是，把API的导出文件加载到 https://editor.swagger.io/ 中去验证是否是正确的OpenAPI格式：

Swagger Editor 在此不仅用于格式校验，更重要的是它会显式暴露不可见或非法字符，这是 Portal 和 CLI 错误信息中缺失的关键线索。

结果很明显，真的是特殊字符(Ñ)导致了问题！

description: The response will contain the Ñreated/updated new resource

真相终于大白了。

虽然修改了文件中的字符后，成功导入（APIM门户和AZ CLI命令都成功）。

但是，还是有一个疑问在心中：为何导出的时候不进行转码，或者是导入的时候不能给出更多的有效信息呢？

参考资料

导入 OpenAPI 规范： https://docs.azure.cn/zh-cn/api-management/import-api-from-oas?tabs=portal

【Azure APIM】API导入功能报错 Unable to parse specified file.

问题描述

导入报错截图：

问题解答

参考资料