Azure APIM外部Redis缓存：外部设键后缓存未命中问题

问题现象 #

• 配置了外部Azure Redis Cache的APIM实例，通过控制台、CLI或.NET SDK直接设置缓存键后，APIM的cache-lookup-value策略始终返回缓存未命中，跟踪日志显示实际查询的键带有2_前缀（如2_ClientID:1）
• 但通过APIM自带的cache-store-value策略存入的缓存键，后续请求能正常命中
• Redis指标显示所有查询均命中，但APIM仍判定为未命中，且在.NET中观察到缓存值前附加了异常字节

APIM缓存查询策略代码 #

<cache-lookup-value key="@("ClientID:" + context.Variables["ClientId"])" variable-name="IsGreen" caching-type="external" />
<choose>
    <when condition="@(context.Variables.GetValueOrDefault<string>("IsGreen") == "true")">
        ...
    </when>
    <otherwise>
        ...
    </otherwise>
</choose>

APIM跟踪日志内容 #

cache-lookup-value (2.803 ms)
{
    "message": "Cache lookup resulted in a miss, variable will not be set.",
    "key": "2_ClientID:1",
    "variableName": "IsGreen"
}

APIM缓存存入策略（可正常命中） #

<!-- 存入后后续请求可命中缓存 -->
<cache-store-value key="ClientID:1" value="true" duration="1440" caching-type="external" />

原因分析 #

APIM对外部Redis缓存的键和值做了自定义处理，导致外部工具存入的内容不兼容：

1. 键前缀自动添加：APIM会为所有缓存键自动生成并添加前缀（如示例中的2_），前缀由APIM内部逻辑决定，外部工具直接设置的键无此前缀，导致APIM查询时无法匹配
2. 值序列化规则：APIM存储缓存值时会附加特定字节头（用于标识值类型等元数据），外部工具存入的纯字符串值不符合APIM的反序列化要求，即使Redis返回了值，APIM也无法解析，最终判定为未命中

解决方案 #

方式1：匹配APIM的缓存格式（推荐） #

若需通过外部工具操作APIM使用的缓存，需严格匹配APIM的键值格式：

• 键的处理：从APIM跟踪日志中获取实际查询的带前缀键（如2_ClientID:1），外部设置时直接使用该完整键
• 值的处理：模拟APIM的序列化逻辑，在值前添加对应字节头。例如字符串类型值需添加\x02字节前缀（对应截图中的异常字节），外部存入时需将值以二进制格式设置为\x02true

方式2：禁用APIM的自定义缓存处理（需谨慎） #

通过APIM高级配置禁用自定义序列化，让APIM直接使用原始Redis键值：

注意：此配置会影响APIM所有外部缓存策略的行为，需确保所有缓存操作均使用原始格式

在APIM实例的Host配置中添加以下设置（可通过Azure门户或ARM模板修改）：

"properties": {
    "cache": {
        "external": {
            "connectionString": "你的Redis连接字符串",
            "enableCachingV2": false
        }
    }
}

内容的提问来源于stack exchange，提问作者theblindprophet