Azure API Management中Liquid模板无法读取JSON数组导致For循环失效

我来帮你排查这个Liquid模板读取JSON数组的问题，这种情况我在APIM里碰到过好几次，大概率是JSON结构和模板路径不匹配或者数组格式异常导致的，咱们一步步来捋清楚：

一、先排查路径与大小写匹配问题 #

Liquid模板对JSON键名是大小写敏感的，而且必须严格匹配JSON的层级结构，这是最常见的坑：

• 先确认你传入的JSON请求里，attachments数组的实际层级是不是真的在body.testEndpointName.request下面？比如如果你的请求JSON里数组是直接挂在body.attachments，那模板里的路径就错了
• 检查键名大小写：比如模板里写的是attachments，但JSON里是首字母大写的Attachments，这种情况Liquid会直接判定数组不存在，循环自然不生效

举个正确的JSON结构示例（要和模板路径对应）：

{
  "testEndpointName": {
    "request": {
      "attachments": [
        {"fileBytes": "dGVzdCBmaWxlIGJ5dGVz"}
      ]
    }
  }
}

二、处理数组可能是单个对象的情况 #

很多时候当只有一个附件时，前端或者上游服务会把数组转成单个对象返回（比如从[{}]变成{}），这时候Liquid的for循环会直接跳过，因为它只能遍历数组类型。

解决办法是用APIM的Liquid过滤器ensure_array，它会自动把单个对象转成数组，空值转成空数组，修改后的模板可以这样写：

<set-body template="liquid">
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://tempuri.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <soap:Body>
            <testEndpointName>
                <request>
                    <Attachments>
                        <!-- 先统一处理数组格式，避免单个对象或空值导致循环失效 -->
                        {% assign attachments = body.testEndpointName.request.attachments | default: empty | ensure_array %}
                        {% for item in attachments %}
                        <testEndpointNameAttachment>
                            {% if item.fileBytes %}
                            <FileBytes>{{item.fileBytes}}</FileBytes>
                            {% endif %}
                            <!-- 其他字段的渲染逻辑继续写在这里 -->
                        </testEndpointNameAttachment>
                        {% endfor %}
                    </Attachments>
                </request>
            </testEndpointName>
        </soap:Body>
    </soap:Envelope>
</set-body>

三、验证APIM是否正确解析了请求体 #

如果上面两步都没问题，那可能是APIM没有正确解析你的JSON请求：

• 确保请求的Content-Type头是application/json，否则APIM可能不会把请求体解析为JSON对象，导致body变量的结构异常
• 可以在set-body策略前加一个trace来查看实际的请求体结构，方便调试：

<trace source="BeforeLiquidTemplate" severity="information">
    @(context.Request.Body.As<string>())
</trace>

测试请求后，在APIM的跟踪日志里就能看到实际传入的body内容，快速定位问题。

备注：内容来源于stack exchange，提问作者JKO