Azure 代金券 Azure 微软云账号 API 网关管理

别再把 APIM 当成高级代理了——Azure API 网关不是摆设，是你的 API 守门员兼翻译官

刚接手 Azure 项目时，我对着「API Management」服务点了三次「创建」又删掉三次。为啥？因为界面太像 Azure Load Balancer——点完就以为万事大吉，结果上线第一天，前端同事发来截图：「/v2/users 返回 500，但后端日志说根本没收到请求」。查了两小时才发现，APIM 根本没配转发策略，连路由规则都空着。它不是个插电即用的网关，而是一套需要「编排」的 API 治理中枢——你得告诉它：谁可以调、怎么调、调错了报什么、调太快怎么拦、调完日志记在哪。

第一步：别急着导入 API，先搞懂 APIM 的三层结构

APIM 不是单个资源，而是「实例 + API + 操作」三级嵌套。新手常犯的错是直接上传 OpenAPI 文件，结果发现「API 已存在」却找不到入口。真相是：APIM 实例（比如叫 prod-apim-westus）是容器；里面可建多个 API（user-service, payment-api）；每个 API 下再定义操作（GET /users/{id}, POST /users）。这就像开餐馆——实例是店面，API 是菜单分类（凉菜/热菜），操作才是具体菜品。漏掉任何一层，请求就进不来。

Azure 代金券 第二步：导入 API？别信「一键同步」，手动校验三处关键

用 OpenAPI 3.0 YAML 导入最省事，但 Azure 会悄悄改三样东西：① 把 basePath 强制转成 /api 前缀（哪怕你写的是 /v3）；② 把 securitySchemes 中的 apiKey 类型自动映射为「订阅密钥」，但不会帮你开订阅功能；③ 所有 consumes/produces 的 MIME 类型会被精简成 application/json，丢掉 text/plain 或 application/xml。建议导入后立刻进「设计」页，点开任意操作，检查「URL 模板」是否带预期前缀、「请求正文类型」是否齐全、「安全方案」是否启用——别等联调才哭。

第三步：策略（Policy）不是 XML 魔术，是可控的中间件流水线

APIM 策略写在 XML 里，看着反人类，实则逻辑极清晰：所有策略按执行顺序从上到下，分 inbound（进）、backend（发给后端前）、outbound（回传前）、on-error（出错时）四段。举个真实案例：某支付接口要求后端接收 X-Request-ID 头，但前端不传。你在 inbound 加一行：
<set-header name="X-Request-ID" exists-action="override"><value>@($context.RequestId)</value></set-header>。再比如，后端只认 Authorization: Bearer xxx，但前端传的是 token=xxx，就用 <set-variable> 提取 token，再用 <set-header> 重组。记住：策略生效需点击右上角「保存」，且仅对当前 API 生效——别改完全局策略却发现只影响了测试 API。

第四步：认证不是勾个框就完事，得选对「身份层」

APIM 支持三种主流认证：① 订阅密钥（最简单，适合内部系统，但粒度粗）；② OAuth 2.0（推荐，对接 Azure AD，可精确到用户/应用权限）；③ JWT 验证（适合已有 Token 体系的团队）。重点来了：启用 OAuth 后，必须在「安全」→「OAuth 2.0」里填好授权服务器地址、客户端 ID、密钥，并在 API 的「设计」页为每个操作手动勾选「要求授权」。否则——前端带着合法 Token 来，APIM 照样返回 401。我们曾因漏勾一个 PUT /orders，导致订单提交永远失败，日志里还显示「未验证」，差点重装 AD。

第五步：监控不是看仪表盘，要盯住三个「死亡指标」

APIM 内置的 Metrics 页面有 20+ 指标，但真正该设告警的只有仨：① Failed Requests（失败率突增＞5%，大概率策略或后端崩了）；② Backend Time（后端响应超 2s，说明下游慢或网络抖动）；③ Gateway Errors（网关自身错误，如策略语法错、证书过期）。特别提醒：默认日志只存 7 天，且「诊断设置」里必须手动关联 Log Analytics 工作区，否则所有 trace 日志都是过眼云烟。我们有次查 48 小时前的 503，发现日志早清空——只能靠 Application Insights 补救。

第六步：排错口诀——「先看跟踪，再查策略，最后抓包」

当请求卡住，别急着重启实例。打开 APIM 的「跟踪」功能（测试控制台旁的小靶心图标），选中请求，点「开始跟踪」，复现问题。你会看到完整生命周期：何时进入 inbound、哪个策略报错（红字标出）、backend 是否发出、outbound 如何处理响应。如果跟踪里显示「policy evaluation failed」，八成是 XML 语法错（比如 <set-variable> 忘了闭合）；如果显示「backend did not respond」，赶紧去后端查连接池或防火墙；如果跟踪里 request headers 全空，回头检查策略里有没有误删 <set-header> 或 <rewrite-uri> 写错了正则。实在不行，用 Azure Network Watcher 抓网关出口流量——你会发现，有些 401 其实是后端返回的，APIM 只是老实转发。

最后送你三条血泪经验

• 测试环境 APIM 实例务必和生产环境同 SKU（Developer 版不支持 VNET 集成，升到 Basic 就跪）；
• 所有策略变更，必须用「测试」按钮在 APIM 控制台里跑通，别信 Postman——它不走网关的 DNS 解析路径；
• 每次发布新 API 版本，记得在「版本集」里设置「默认版本」，否则老链接会 404，前端连降级都来不及。

APIM 不是银弹，但它能把 API 从「能用」变成「稳用」「可控用」「可审计用」。下次再看到那个蓝色云朵图标，别只想到「又一个待付费服务」——想想它正默默帮你挡掉第 1279 个恶意扫描、重写第 3 个不合规 Header、把 500 错误转化成带 traceID 的友好提示。这才是云原生时代，靠谱工程师该有的体面。