Filtros de solicitud HTTP con funciones de Edge

IMPORTANT
Funciones de AEM Edge se encuentra en la versión beta. Las funciones y la documentación pueden cambiar. Para obtener comentarios, comuníquese con aemcs-edgecompute-feedback@adobe.com.

Obtenga información sobre cómo implementar el filtrado de solicitudes HTTP con funciones Edge de AEM para reescribir o redirigir solicitudes, o modificar respuestas HTTP.

Cuándo filtrar solicitudes HTTP con funciones de Edge

Una función Edge de AEM puede actuar como un proxy inverso que realiza un procesamiento avanzado de la solicitud y la respuesta antes de que lleguen al origen o al cliente.

Los dos escenarios son:

Ajustar la solicitud antes de que llegue al origen

Interceptar el tráfico en el camino al origen para:

  • Vuelva a escribir el origen, la ruta de acceso o la consulta de la solicitud. Dirija la solicitud a un backend, ruta o cadena de consulta diferente para que el origen reciba el recurso correcto.
  • Reescribir encabezados de solicitud. Añada, quite o modifique encabezados antes de que la solicitud llegue al origen. Por ejemplo, agregue un encabezado geográfico o de acceso que el origen espera, quite encabezados que el origen ignora o cambie un valor de encabezado para modificar el comportamiento de la solicitud.

Modifique la respuesta antes de que llegue al cliente

Interceptar el tráfico de vuelta al cliente (visitante) para:

  • Cambiar el HTML de respuesta. Inserte JavaScript, contenido personalizado, vuelva a escribir vínculos o una unión en un encabezado y pie de página antes de que la página llegue al explorador.
  • Redireccionar en el perímetro. Proporcione un gran conjunto de redirecciones de URL de heredadas a nuevas desde la CDN, especialmente cuando las reglas de redirección requieren lógica programática.
  • Personalizar por contexto de solicitud. Cambie una página o sección de una página por geolocalización, dispositivo o audiencia para los visitantes públicos. Esto se aplica al tráfico de publicación en el dominio del sitio, no al tráfico de creación.

Implementación del filtrado de solicitudes HTTP

El filtrado de solicitudes HTTP utiliza dos archivos. El archivo config/cdn.yaml decide qué tráfico interceptar y enrutar a la función Edge de AEM. El archivo src/index.js realiza el ajuste de solicitud o respuesta.

El selector de origen y el nombre de función deben alinearse. Si edgeFunctions.yaml declara my-edge-function, el selector de origen usa edgefunction-my-edge-function en cdn.yaml.

Configuración del filtro CDN

# config/cdn.yaml (origin selector excerpt)
kind: "CDN"
version: "1"
data:
  originSelectors:
    rules:
      - name: route-to-edge-function
        when:
          allOf:
            - { reqProperty: tier, equals: "publish" } # publish traffic only; skip author
            - { reqProperty: domain, equals: "www.example.com" } # your site hostname
            - { reqProperty: originalPath, matches: "(/[^./]+|\\.html|/)$" } # page URLs; skip static assets (.css, .js, images, fonts)
            # - { reqProperty: method, in: ["GET", "HEAD"] } # optional: navigation only; skip POST, PUT, and other methods with bodies
            - { reqHeader: x-edgefunction-request, exists: false } # skip loopback requests to prevent infinite loops
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>

Si alguna condición falla, la solicitud nunca llega a la función Edge de AEM. Comience con las menores condiciones que necesita su función y añada más solo para que el enrutamiento sea más preciso. Para ver todas las propiedades y operadores admitidos, consulte Selectores de origen.

Implementar el controlador

Cada función de AEM Edge registra un controlador de eventos de captura. Utilice el controlador para ajustar la solicitud antes de que alcance el origen, modificar la respuesta antes de que llegue al cliente o ambos.

El siguiente fragmento de código muestra el filtrado de solicitudes y la modificación de respuestas en una función Edge de AEM.

// src/index.js
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  const req = event.request;
  const url = new URL(req.url);

  try {
    // ------------------------------------------------------------
    // --- Request filtering: adjust before origin ---
    // ------------------------------------------------------------

    // Example: Rewrite origin, path, or query
    // Replace origin based on some criteria such as path or query
    const newOriginRequest = new Request(`https://origin.example.com${url.pathname}${url.search}`);
    const newOriginResponse = await fetch(newOriginRequest);
    // Return the new origin response
    return newOriginResponse;

    ...

    // Example: Rewrite request headers before reaching the origin
    // Add or modify headers before the request reaches the origin, like adding an authorization token based on exchange with an external service.
    const originRequest = new Request(req, {
      headers: new Headers({ ...Object.fromEntries(req.headers), "Authorization": "Bearer <token>" }),
    });
    const originResponse = await fetch(originRequest);
    return originResponse;

    ...

    // ------------------------------------------------------------
    // --- Response filtering: modify before client ---
    // ------------------------------------------------------------

    // Example: Change response HTML (fetch from origin, transform the body)
    // Fetch the response from the origin, transform the body, and return the transformed response.
    const originRequest = new Request(`https://origin.example.com${url.pathname}`);
    const originResponse = await fetch(originRequest);
    const transformedHtml = transformHtml(await originResponse.text());
    return new Response(transformedHtml, { status: 200, headers: originResponse.headers });

    ...

    // Example: Redirect at the edge
    // Redirect the client to a new path, like a legacy URL to a new URL.
    return Response.redirect("https://www.example.com/new-path", 301);

    ...

    // Example: Personalize by request context (geo, device, or audience)
    // Fetch the response from the origin, personalize the body, and return the personalized response.
    const originRequest = new Request(`https://origin.example.com${url.pathname}`);
    const originResponse = await fetch(originRequest);
    const personalizedHtml = personalizeHtml(await originResponse.text());
    return new Response(personalizedHtml, { status: 200, headers: originResponse.headers });

    return new Response("Not implemented", { status: 501 });
  } catch (err) {
    console.log(err);
    return new Response("Error", { status: 500 });
  }
}

Puntos clave:

Concepto
Detalle
Filtro de CDN
when + allOf en cdn.yaml solo enruta el tráfico que coincida con su función AEM Edge
Filtrado de solicitudes
Generar un(a) nuevo(a) Request con un origen, ruta de acceso, consulta o encabezados diferentes antes de fetch() en el origen
Filtrado de respuestas
Devuelve un nuevo(a) Response con contenido transformado, redireccionado o personalizado
Bucle invertido CDN
Establezca un encabezado centinela en las llamadas internas de fetch() para que la CDN enrute el tráfico de bucle invertido al origen

Directrices de diseño

  • Mantenga los filtros lo más estrechos posible.
  • Restringir las funciones de navegación a GET y HEAD.
  • Evite los bucles infinitos en bucle CDN al establecer un encabezado centinela en las llamadas fetch() internas.
  • Implementar cdn.yaml actualizado a través de su canalización de configuración de Cloud Manager.

Impedir bucles infinitos en bucle invertido de CDN

Se puede producir un bucle infinito cuando una función Edge de AEM recupera contenido del origen a través de la CDN. Esa captura vuelve a entrar en la CDN, coincide con la misma regla de selector de origen y se enruta de nuevo a la función.

Para evitarlo, puede excluir las solicitudes de bucle invertido de la regla de selector de origen estableciendo un encabezado centinela (por ejemplo, x-edgefunction-request). La solicitud inicial del visitante no tiene encabezado y llega a la función Edge de AEM. La solicitud de bucle invertido lleva el encabezado, produce un error en la condición y enruta al origen en su lugar.

Los siguientes fragmentos de código y configuración muestran cómo evitar bucles infinitos en bucle CDN.

// src/index.js
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
...

// In the handler: set the sentinel on the loopback fetch
const loopbackRequest = new Request(`https://www.example.com${url.pathname}`, {
  headers: { "x-edgefunction-request": "true" },
});
await fetch(loopbackRequest);

Consulte Ejemplos de funciones de AEM Edge para ver cómo establecer el encabezado centinela en el controlador de funciones de AEM Edge.

# config/cdn.yaml (origin selector excerpt)
kind: "CDN"
version: "1"
data:
  originSelectors:
    rules:
      - name: route-to-edge-function
        when:
          allOf:
            ...
            - { reqHeader: x-edgefunction-request, exists: false } # skip loopback requests to prevent infinite loops
            ...

Consulte Ejemplos de funciones de AEM Edge para ver cómo excluir solicitudes que ya llevan el encabezado centinela en la configuración de CDN.

Ejemplos completos

El repositorio Ejemplos de funciones Edge de AEM incluye funciones interceptoras con config/cdn.yaml reglas completas:

Ejemplo
Repositorio
Lo que demuestra
Transformador de AEM as a Cloud Service HTML
publish-delivery-transformer
Publicar el filtro de página para sitios de AEM as a Cloud Service que inserta un fragmento de JavaScript en la respuesta de HTML y evita el bucle invertido de CDN
Transformador de Edge Delivery HTML
transformador-entrega-perimetral
Publicar el filtro de página para los sitios de Edge Delivery Services que inserta el encabezado y pie de página del sitio en la respuesta de HTML
Búsqueda de mapa de redireccionamiento
publish-delivery-redirect-maps
Filtro de página GET/HEAD que redirige a una URL heredada y evita el bucle invertido de CDN

Recursos adicionales

recommendation-more-help
experience-manager-learn-help-cloud-service