Compartir a través de

Administración de variables para fragmentos de directiva

SE APLICA A: Todos los niveles de API Management

Las variables de contexto permiten el uso compartido de datos entre fragmentos de directiva para escenarios de canalización avanzados. La administración de variables adecuada es fundamental para crear canalizaciones confiables con un rendimiento óptimo. El control incorrecto puede provocar errores en tiempo de ejecución, problemas de rendimiento y comportamiento impredecible.

Aspectos básicos de las variables

Las variables de contexto permiten compartir datos de forma segura entre subprocesos entre fragmentos de directiva y se crean mediante la política integrada set-variable. Cada solicitud mantiene su propio contexto de variable aislada, lo que garantiza que las solicitudes simultáneas no interfieran entre sí.

Gestión del ciclo de vida de variables

  • Ámbito de solicitud: las variables solo existen durante una sola solicitud y se recopilan automáticamente elementos no utilizados cuando se completa la solicitud.

  • Persistencia de la fase: Las variables establecidas en la fase de entrada permanecen disponibles durante la fase de backend, fase de salida y fase de error dentro de la misma solicitud.

  • Aislamiento de subprocesos: el aislamiento estricto de subprocesos garantiza que cada solicitud se ejecute en su propio subproceso con su propio objeto de contexto, lo que impide la interferencia de datos entre solicitudes.

  • Actualizaciones secuenciales: cualquier fragmento puede modificar variables existentes, con fragmentos posteriores sobrescribir valores anteriores. La ejecución secuencial elimina la necesidad de mecanismos de bloqueo.

  • Umbral de almacenamiento: la plataforma optimiza la administración de variables de contexto para colecciones pequeñas, normalmente 50 variables por solicitud o menos.

Establecimiento y recuperación de variables en fragmentos

<!-- Example: Set a request-id context variable that is a required value for other fragments -->
<set-variable name="request-id" value="@{
    var requestId = context.Request.Headers.GetValueOrDefault("X-Request-ID", "");
    if (string.IsNullOrEmpty(requestId)) {
        return Guid.NewGuid().ToString();
    }
    return requestId;
}" />

<!-- Example: Retrieve the same request-id context variable safely in another fragment -->
<set-header name="X-Correlation-ID" value="@{
    return context.Variables.GetValueOrDefault<string>("request-id", "unknown");
}" />

procedimientos recomendados

Uso del acceso seguro a variables

Tenga siempre cuidado con los posibles valores NULL, use el acceso seguro con GetValueOrDefaulty proporcione valores predeterminados significativos para todo el acceso a variables:

<!-- Safe access with default value -->
<set-variable name="log-level" value="@{
    return context.Variables.GetValueOrDefault<string>("config-log-level", "INFO");
}" />

<!-- Safe string interpolation using GetValueOrDefault -->
<set-variable name="cache-key" value="@{
    var userId = context.Variables.GetValueOrDefault<string>("auth-user-id", "anon");
    var resource = context.Variables.GetValueOrDefault<string>("request-resource", "default");
    
    return $"cache:{userId}:{resource}";
}" />

Comprobación de la existencia de variables

Asegúrese de que existan variables creadas por fragmentos de requisitos previos antes de acceder a ellas. Cuando falten dependencias, elija entre dos estrategias:

Estrategia 1: Error rápido (dependencias críticas)

Devuelve una respuesta de error cuando faltan dependencias críticas:

<choose>
    <when condition="@(!context.Variables.ContainsKey("user-id"))">
        <!-- Critical dependency missing - fail immediately -->
        <return-response>
            <set-status code="500" reason="Internal Server Error" />
            <set-body>{"error": "Required variable missing", "missing_dependency": "user-id"}</set-body>
        </return-response>
    </when>
    <otherwise>
        <!-- Safe to proceed - use the user-id variable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </otherwise>
</choose>

Estrategia 2: Controlar correctamente (dependencias opcionales)

Continúe la ejecución con el comportamiento alternativo adecuado cuando falten dependencias opcionales.

<choose>
    <when condition="@(context.Variables.ContainsKey("user-id"))">
        <!-- Optional variable available - use it -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </when>
    <otherwise>
        <!-- Fallback to default when variable unavailable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>unknown</value>
        </set-header>
    </otherwise>
</choose>

Minimizar el acceso a las variables

Reduzca las búsquedas de variables de contexto mediante la consolidación de varios accesos en expresiones únicas:

<!-- Good: Single consolidated access -->
<set-variable name="log-entry" value="@{
    var level = context.Variables.GetValueOrDefault<string>("log-level", "INFO");
    var requestId = context.Variables.GetValueOrDefault<string>("request-id", "unknown");
    return $"[{level}] Request {requestId} completed";
}" />

<!-- Avoid: Multiple separate accesses -->
<set-variable name="level-prefix" value="@("[" + context.Variables.GetValueOrDefault<string>("log-level", "INFO") + "]")" />
<set-variable name="request-suffix" value="@("Request " + context.Variables.GetValueOrDefault<string>("request-id", "unknown") + " completed")" />
<set-variable name="log-entry" value="@(context.Variables.GetValueOrDefault<string>("level-prefix", "") + " " + context.Variables.GetValueOrDefault<string>("request-suffix", ""))" />

Mantener tipos coherentes

Use el control explícito de tipos para obtener un rendimiento y una confiabilidad óptimos. Al trabajar con expresiones de directiva, especifique el tipo esperado con el @() operador :

<!-- Set as boolean, use as boolean -->
<set-variable name="should-log-debug" value="@(true)" />
<choose>
    <when condition="@(context.Variables.GetValueOrDefault<bool>("should-log-debug", false))">
        <!-- Include detailed debug information in logs -->
    </when>
</choose>

Contenido relacionado

  • Last updated on