Generar un extremo de API con funciones de Edge

Una función de AEM Edge es un módulo de JavaScript que se ejecuta en Adobe CDN (Fastly Compute). Lo expone como uno o más extremos HTTP al emparejar las reglas del selector de origen de CDN con un controlador de eventos de captura en su código.

Esta página cubre el contrato y los archivos de claves. Puede escribir cualquier lógica en el controlador, incluidas las llamadas salientes de fetch() a otros sistemas. Mantenga el controlador rápido y de corta duración para que se ajuste al tiempo de ejecución del perímetro.

Requisitos previos

Para configurarlo por primera vez, consulta Configuración en AEM as a Cloud Service o Configuración en Edge Delivery Services.

Cómo llega una solicitud HTTP a su código

Una solicitud llega a la función Edge de AEM en dos pasos: el selector de origen de CDN enruta el extremo a la función y, a continuación, se ejecuta el controlador de eventos de recuperación.

Browser → CDN origin selector (cdn.yaml) → AEM Edge Function (index.js) → Your handler logic (optional fetch to other systems)

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.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function #<name-of-the-function>

# config/cdn.yaml (origin selector excerpt)
kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-status-endpoint-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/status" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: false # false to use the CDN cache for this path
      - name: route-my-api-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/my-api" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: true # true to bypass the CDN cache for this path

Cada extremo necesita su propia regla de selector de origen en cdn.yaml. Una función de AEM Edge puede servir varios extremos, pero la CDN debe reenviar cada ruta a esa función. Establezca skipCache: false para permitir el almacenamiento en caché de CDN para respuestas estables o skipCache: true para omitir la caché de CDN para respuestas dinámicas o personalizadas.

Para ver las opciones del selector de origen, consulte Selectores de origen.

Administrar solicitudes

Cada función de AEM Edge registra un controlador de eventos de captura. Adobe CDN invoca ese controlador para cada solicitud coincidente. El controlador lee el elemento Request entrante, ejecuta la lógica y devuelve un elemento Response.

// src/index.js
import { myApiHandler } from "./my-api.js";
import * as response from "./lib/response.js";

// entry point for the AEM Edge Function
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  // event.request is a standard Fetch API Request (method, URL, headers, body)
  const req = event.request;
  const url = new URL(req.url);

  try {
    // endpoint matching
    if (url.pathname === "/status" && req.method === "GET") {
      return new Response("OK", { status: 200 });
    } else if (url.pathname === "/my-api" && req.method === "GET") {
      return await myApiHandler(req, event.client);
    }
    // add more endpoints here

    return response.notFound();
  } catch (err) {
    console.log(err);
    return response.error();
  }
}

Puntos clave:

El extremo que coincide se encuentra en index.js. A medida que crezcan los extremos, mueva la lógica del controlador a archivos separados e impórtelos, como hace my-api.js en el ejemplo anterior. Consulte Proporcionar varios extremos con funciones de Edge para ver patrones a medida que se expande la superficie de la API.

Escriba la lógica del controlador

Dentro de cada controlador de extremos, puede ejecutar cualquier JavaScript que se ajuste al tiempo de ejecución de Edge. Mantenga el trabajo rápido y de corta duración. Prefiera transformaciones ligeras, búsquedas geográficas, respuestas JSON o HTML simples y agregaciones pequeñas en lugar de equipos pesados o de larga duración.

Una respuesta mínima tiene este aspecto:

if (url.pathname === "/status" && req.method === "GET") {
  return new Response("OK", { status: 200 });
}

Puede devolver JSON, HTML o texto sin formato. Establezca encabezados en Response para controlar el tipo de contenido y el almacenamiento en caché:

return new Response(JSON.stringify({ status: "ok" }), {
  status: 200,
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "public, max-age=300",
  },
});

Si necesita datos de otro sistema, llámele con fetch(). Guarde las credenciales en la función Edge de AEM. No exponga secretos en el cliente JavaScript.

// src/my-api.js
async function myApiHandler(req, client) {
  const backendRequest = new Request("https://api.example.com/data");

  // optionally, you can add headers to the request
  // backendRequest.headers.set("Authorization", `Bearer <your-access-token>`);

  const backendResponse = await fetch(backendRequest);

  if (!backendResponse.ok) {
    return new Response("Backend error", { status: 502 });
  }

  const data = await backendResponse.json();

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "max-age=300",
    },
  });
}

export { myApiHandler };

Las llamadas salientes fetch() suelen seguir este patrón:

Se aplican límites de plataforma. Cada invocación admite hasta 32 llamadas de captura salientes. Para ver el comportamiento de la caché en las llamadas de captura, consulte Almacenamiento en caché en las funciones de AEM Edge.

Más ejemplos de código

Para ver ejemplos prácticos completos, consulte la plantilla de funciones de AEM Edge:

Recursos adicionales