Compartir a través de

Ejecución de directivas con fragmentos

SE APLICA A: Todos los niveles de API Management

Los escenarios de canalización avanzados con comportamiento personalizado a lo largo del ciclo de vida de la solicitud y la respuesta se crean mediante fragmentos de directiva. Las directivas centrales en los niveles de producto y API insertan fragmentos mediante la directiva include-fragment . Los fragmentos se pueden compartir entre las directivas de producto y API para evitar la duplicación y mantener una separación clara de responsabilidades.

Inserción de fragmentos

Uso de directivas centrales para insertar fragmentos

Las definiciones de directivas de API y productos sirven como orquestadores que insertan fragmentos en un orden específico para crear la canalización completa de solicitudes y respuestas. En el ejemplo siguiente se muestran los fragmentos insertados por una definición de directiva:

<policies>
  <inbound>
    <include-fragment fragment-id="security-context" />
    <include-fragment fragment-id="rate-limiting" />
    <include-fragment fragment-id="request-logging" />
    <base />
  </inbound>
  <backend>
    <include-fragment fragment-id="backend-selection" />
    <base />
  </backend>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
  <on-error>
    <include-fragment fragment-id="error-response" />
  </on-error>
</policies>

Conceptos clave

  • Orden secuencial: los fragmentos se ejecutan en el orden en que se incluyen.
  • Colocación de fases: los fragmentos se insertan en las fases de directivas adecuadas (entrantes, back-end, salientes, en caso de error) en función de su funcionalidad.
  • Administración de dependencias: los fragmentos posteriores pueden basarse en variables de contexto establecidas por fragmentos anteriores en la secuencia.

procedimientos recomendados

Insertar fragmentos basados en el alcance

Asegúrese de que las directivas de productos y API funcionen conjuntamente dividiendo de forma eficaz las responsabilidades de los fragmentos según el ámbito:

  • Directiva de producto: inserta fragmentos que realizan un comportamiento específico del producto que varía en todos los productos.
  • Directiva de API: inserta fragmentos que se aplican en todos los productos.

Reutilización de fragmentos para evitar la duplicación

Elimine la duplicación cuando se necesite la misma lógica en las directivas de producto y API mediante la reutilización del mismo fragmento. En este ejemplo, el circuit-breaker fragmento se reutiliza:

<!-- Product Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="security-context" />
    <include-fragment fragment-id="rate-limiting" />
    <base />
  </inbound>
  <backend>
    <include-fragment fragment-id="backend-selection" />
    <base />
  </backend>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
</policies>

<!-- API Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="request-logging" />
    <base />
  </inbound>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
</policies>

Document fragment dependencies and data contracts (Dependencias de fragmentos de documentos y contratos de datos)

Documente las relaciones de dependencia y los contratos de datos en cada fragmento para aclarar qué fragmentos y variables son necesarios. Use comentarios para especificar:

  • Dependencias: otros fragmentos que deben ejecutarse antes de este fragmento
  • Requiere: Variables de contexto que deben existir antes de que se ejecute este fragmento
  • Produce: variables de contexto que este fragmento genera para fragmentos posteriores
<fragment fragment-id="rate-limiting-fragment">
  <!-- Dependencies: security-context-fragment, config-cache-fragment -->
  <!-- Requires: subscription-key variables -->
  <!-- Produces: rate-limit-applied, rate-limit-remaining variables -->
  
  <!-- Verify dependencies before execution -->
  <choose>
    <when condition="@(!context.Variables.ContainsKey("subscription-key"))">
      <return-response>
        <set-status code="500" reason="Internal Server Error" />
        <set-body>Rate limiting requires security context</set-body>
      </return-response>
    </when>
  </choose>
  
  <!-- Rate limiting logic -->
  <set-variable name="rate-limit-applied" value="@(true)" />
  <set-variable name="rate-limit-remaining" value="@(95)" />
</fragment>

Uso de la inclusión de fragmentos condicionales

Implemente lógica condicional dentro de directivas centrales para incluir de forma dinámica fragmentos basados en características de solicitud, opciones de configuración o contexto en tiempo de ejecución. Este patrón permite canalizaciones de procesamiento flexibles que se adaptan a diferentes escenarios:

<!-- Product Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="config-cache" />
    <include-fragment fragment-id="request-analysis" />
    
    <!-- Conditional authentication with custom logic based on request type -->
    <choose>
      <when condition="@(context.Request.Headers.GetValueOrDefault("Authorization", "").StartsWith("Bearer"))">
        <include-fragment fragment-id="security-jwt" />
      </when>
      <otherwise>
        <include-fragment fragment-id="security-api-key" />
      </otherwise>
    </choose>
    
    <base />
  </inbound>
</policies>

Conservar el cuerpo de la solicitud entre fragmentos

Cuando los fragmentos necesitan leer el cuerpo de la solicitud para su procesamiento (como extraer metadatos o validación), siempre use preserveContent: true para asegurarse de que el cuerpo de la solicitud permanezca disponible para los fragmentos posteriores y el reenvío back-end.

<set-variable name="request-metadata" value="@{
  try {
    // CRITICAL: preserveContent: true ensures body remains available for other fragments and backend
    var body = context.Request.Body.As<string>(preserveContent: true);
    var requestData = JObject.Parse(body);
    
    // Extract metadata without consuming the body
    return new JObject {
      ["user-id"] = requestData["user"]?.ToString() ?? "anonymous"
    };
  } catch {
    return new JObject();
  }
}" />

Sin preserveContent: true, leer el cuerpo de la solicitud lo consume, lo que hace que no esté disponible para los siguientes fragmentos o servicios de back-end.

Prueba y depuración

La depuración eficaz de la pasarela de fragmentos requiere un enfoque sistemático para comprender el flujo de ejecución y el estado de las variables. En esta sección se muestran los enfoques de depuración que minimizan el impacto en el rendimiento al maximizar la visibilidad del procesamiento de solicitudes.

Habilitar encabezados de depuración

Utilice encabezados de depuración para capturar el estado de las variables en un punto específico del pipeline para solucionar problemas. Los encabezados de depuración aparecen en los encabezados de respuesta HTTP y son visibles para los clientes de API. En lugar de agregar encabezados de depuración individuales a lo largo de fragmentos, cree un fragmento de administración de encabezados dedicado que consolide todos los encabezados de depuración en una ubicación. Este enfoque centralizado garantiza la coherencia y mejora la capacidad de mantenimiento.

<!-- Example: Dedicated header fragment -->
<fragment fragment-id="debug-headers">
  <!-- Debug headers for troubleshooting -->
  <set-header name="X-Debug-Request-Type" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("request-type", "unknown"))</value>
  </set-header>
  <set-header name="X-Debug-Selected-Backend" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("selected-backend", "unknown"))</value>
  </set-header>
  <set-header name="X-Debug-Request-ID" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("request-id", "unknown"))</value>
  </set-header>
</fragment>

Ubicación de la canalización:

Incluya el fragmento de administración de encabezados en la sección de salida de la directiva de producto, después de que todos los demás fragmentos se ejecuten:

<policies>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <include-fragment fragment-id="resource-tracking" />
    <!-- Headers fragment - placed last to capture final state -->
    <include-fragment fragment-id="debug-headers" />
    <base />
  </outbound>
</policies>

Alternativa - encabezados de depuración en línea:

Para escenarios simples o al probar fragmentos individuales, puede agregar encabezados de depuración directamente:

<set-header name="X-Debug-Variables" exists-action="override">
    <value>@{
        var debug = new JObject();
        debug["request-id"] = context.Variables.GetValueOrDefault<string>("request-id", "not-set");
        debug["request-type"] = context.Variables.GetValueOrDefault<string>("request-type", "not-set");
        debug["selected-backend"] = context.Variables.GetValueOrDefault<string>("selected-backend", "not-set");
        return debug.ToString(Formatting.None);
    }</value>
</set-header>

Ejecución de fragmentos de seguimiento

Cree rutas de ejecución para comprobar la secuenciación de fragmentos e identificar qué fragmentos se ejecutan a través de las políticas de API y de producto. Esta técnica es fundamental para depurar la lógica condicional y comprender por qué se omitieron determinados fragmentos. Agregue este código al principio de cada fragmento, reemplazando "nombre-fragmento" por el nombre del fragmento real:

<set-variable name="execution-trace" value="@{
    var trace = context.Variables.GetValueOrDefault<string>("execution-trace", "");
    return trace + "→fragment-name";
}" />

Para ver la ruta de navegación, use la directiva de seguimiento integrada para registrar el flujo de ejecución:

<trace source="Fragment-Execution" severity="information">
    <message>@(context.Variables.GetValueOrDefault<string>("execution-trace", ""))</message>
</trace>

Depuración mediante el seguimiento de solicitudes

Habilite el seguimiento de solicitudes para capturar rastros de ejecución detallados a través del pipeline de políticas para resolver problemas de comportamiento inesperado. Para habilitar el seguimiento de solicitudes, el cliente debe:

  1. Autenticación con la API de administración API Management para obtener el token de acceso
  2. Obtención de credenciales de depuración para obtener un token de seguimiento de depuración
  3. Envío de solicitudes con el seguimiento habilitado mediante el token de depuración
  4. Recuperar la salida de seguimiento completa que muestra el flujo de ejecución y los detalles de la directiva

La salida del seguimiento incluye información detallada sobre el orden de ejecución de los fragmentos, el estado de las variables y el procesamiento de las directivas que pueden ayudar a identificar problemas en la pasarela. Para más información, consulte Habilitación del seguimiento de una API.

Para ayudar a solucionar problemas de canalización, copie la salida de seguimiento completa y proporciónela a GitHub Copilot para obtener análisis detallados y recomendaciones sobre cómo resolver problemas.

Contenido relacionado

  • Last updated on