【Azure APIM】API导入功能报错 Unable to parse specified file.
问题描述
在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
