Funciones de Edge de AEM aem-edge-functions

AEM Edge Functions le permite ejecutar JavaScript en la capa de CDN, lo que acerca el procesamiento de datos al usuario final. Esto reduce la latencia y permite experiencias dinámicas y adaptables sin necesidad de realizar un viaje de ida y vuelta al origen.

Los casos de uso comunes incluyen los siguientes:

AEM Edge Functions es compatible con Edge Delivery Services y AEM as a Cloud Service Java-stack, para clientes de AEM Sites.

Siga este tutorial para ver una explicación detallada de las variaciones de pila Java de Edge Delivery Services y AEM as a Cloud Service.

Consulte también este repositorio de ejemplos de código, incluida la vinculación de contenido en la red de distribución de contenido (CDN) y la recuperación correcta de contenido desde el origen del nivel de publicación de AEM.

Principales ventajas key-benefits

Requisitos previos prerequisites

Configuración setup

Instalación de la CLI de Adobe install-adobe-cli

Instale la CLI de Adobe Developer (aio):

npm install -g @adobe/aio-cli

Instale el complemento Funciones de AEM Edge:

aio plugins install @adobe/aio-cli-plugin-aem-edge-functions

Autentique y configure el complemento para su entorno:

aio login
aio aem edge-functions setup

El comando setup le solicita que inicie sesión y, a continuación, seleccione el entorno de AEM en el que desea utilizar las funciones de Edge de AEM.

Clonar la plantilla boilerplate

Copie aem-edge-functions-boilerplate en su propio repositorio y luego instale las dependencias:

npm install

Registre su función de AEM Edge register-your-function

Las funciones de AEM Edge se declaran en un archivo de configuración de YAML y se implementan a través de la canalización de configuración de Cloud Manager.

​1. Configurar una canalización de configuración configuration-pipeline

Antes de crear una función perimetral, asegúrese de que en Cloud Manager exista una canalización de configuración para su entorno (si utiliza la pila Java de AEM) o una canalización de Edge Delivery Services si el proyecto se implementa con Edge Delivery Services. Consulte Usar canalizaciones de configuración para obtener información sobre cómo configurar las canalizaciones.

​2. Declarar la función de Edge declare-functions

Cree un archivo con el nombre edgeFunctions.yaml en el directorio de configuración:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
    # add advanced configuration under here

Los entornos de pila de Java tienen 1 función Edge y las implementaciones de Edge Delivery Services tienen 3 funciones Edge. Las claves de nivel superior opcionales son las siguientes:

Vea configuraciones avanzadas como configs, secrets y kvs en la sección de configuración avanzada a continuación.

​3. Implementación de la función Edge mediante Cloud Manager deploy-functions-via-cm

Con Cloud Manager, implemente la canalización para que la función perimetral se registre en la CDN.

Crear, generar e implementar código de función de AEM Edge build-deploy

Autor author

Escriba su lógica empresarial de código de función perimetral, usando la src carpeta 🔗 de plantillas como punto de partida.

Generar build

Empaquete el código de función perimetral para la implementación:

aio aem edge-functions build

Implementación deploy

Implemente el código de función de Edge empaquetado en la función de Edge con nombre. El argumento function-name debe coincidir con el valor name de edgeFunctions.yaml:

aio aem edge-functions deploy <function-name>

Prueba test

Asegúrese de que la función Edge funciona según lo esperado. Puede probarlo en:

edgefunction-pXXXXX-eYYYYY-<function name>.adobeaemcloud.com/<path>

Por ejemplo, para la pila Java de AEM:

o para Edge Delivery Services:

Este dominio con el prefijo edgefunction solo se usa para la depuración, pero no se debe hacer referencia a para el tráfico en directo porque no se garantiza que sea un nombre estable. Para determinar el valor de dAAAA, consulte el resultado del comando deploy.

Alambre en el flujo de entrega de contenido wiring

El tráfico de funciones de Edge debe enviarse al dominio del sitio web, que suele ser un dominio personalizado para AEM Java-stack, y debe ser un dominio personalizado para Edge Delivery Services Sites.

​1. Definir selectores de origen origin-selectors

Las funciones de Edge se invocan enrutando el tráfico de CDN a ellas a través de reglas de selector de origen. Agregue lo siguiente al archivo de configuración cdn.yaml (o cree uno si no existe):

kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-weather-to-edge-function
        when: { reqProperty: path, equals: "/weather" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function
      - name: route-hello-world-to-edge-function
        when: { reqProperty: path, equals: "/hello-world" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function

Las reglas del selector de origen permiten dirigir el tráfico a las funciones perimetrales en función de cualquier condición disponible en el motor de reglas de CDN, como una ruta específica, un dominio o un encabezado de solicitud. Varias reglas pueden enrutar diferentes rutas a la misma función de Edge. Consulte Selectores de origen para obtener la sintaxis completa de la regla.

​2. Implementar la configuración deploy-to-cdn

Confirme cdn.yaml a su repositorio Git de Cloud Manager y almacene en déclencheur la canalización de configuración. Una vez que la canalización se complete correctamente, los puntos finales de la función Edge estarán disponibles en:

Para la depuración, puede hacer referencia a la función perimetral en el dominio publish-pXXXXX-eYYYYY.adobeaemcloud.com (para la pila Java de AEM) o publish-pXXXXX-dYYYYY.adobeaemcloud.com (para los sitios Edge Delivery Services). No utilice este dominio para el uso en producción, ya que no se garantiza que sea un nombre estable. Para determinar el valor de dAAAA, consulte el resultado del comando deploy.

Desarrollo local local-development

Ejecutar localmente local-run

Iniciar un servidor de desarrollo local en http://127.0.0.1:7676:

aio aem edge-functions serve

Consulte esta Documentación de cómputo de JavaScript para obtener detalles sobre lo que admite el tiempo de ejecución local.

Prueba test-localdev

Ejecute el grupo de pruebas con Mocha:

npm run test

Depuración remota remote-debugging

La CDN administrada por Adobe no expone un depurador remoto, pero sí un flujo de registro. Siga los registros de una función implementada para recibir la salida console.log directamente en el terminal:

aio aem edge-functions tail-logs <function-name>

Almacenamiento en caché y depuración de caché caching

Las funciones de Edge pueden reducir significativamente la carga de origen y mejorar los tiempos de respuesta al almacenar en caché los datos en el perímetro de. Sin embargo, el almacenamiento en caché requiere un diseño intencional, especialmente en las funciones de Edge en las que hay dos capas de caché independientes implicadas:

Browser → AEM CDN (CDN Cache) → AEM Edge Functions (Fetch Cache) → Backend (AEM, APIs, etc.)

Antes de configurar el almacenamiento en caché, considere cómo se comporta su contenido:

Dado que la CDN y la caché de recuperación interna de la función Edge funcionan de forma independiente, un cambio en los datos subyacentes requiere la invalidación deliberada de ambas capas. Comprender esta arquitectura es esencial para una administración fiable de la caché.

Para obtener instrucciones técnicas detalladas sobre la configuración del comportamiento del almacenamiento en caché, el control de la duración de la caché, el uso de claves de sustitución y la depuración del contenido almacenado en caché, consulte Almacenamiento en caché en las funciones de Edge de AEM.

Limitaciones limitations

Máximo de llamadas de recuperación salientes por invocación max-fetch-calls

Las funciones de AEM Edge aplican un límite estricto de 32 solicitudes back-end por ejecución (es decir, por cada solicitud entrante gestionada por su función). Una vez alcanzado este límite, cualquier llamada adicional de fetch() genera el siguiente error:

Requested backend named '…' does not exist

Cuando vea este error y la configuración de origen sea correcta, la causa más probable es que se haya agotado la cuota de solicitudes back-end por invocación. Consulte Límites de recursos de Fastly Compute para obtener la lista completa de límites de plataforma.

Configuración avanzada de funciones de Edge advanced-function-configuration

Orígenes origins

De forma predeterminada, las funciones de Edge pueden recuperarse de cualquier origen. Para restringir una función a un conjunto definido de orígenes, declárelos en origins en edgeFunctions.yaml:

origins:
  - name: my-origin-name
    domain: example.com

Haga referencia al origen con nombre en el código de función mediante la opción de captura backend:

const request = new Request("https://example.com/test");
const response = await fetch(request, { backend: "my-origin-name" });

Variables de configuración de función Edge function-configuration

Exponga las variables de entorno a sus funciones usando la clave configs en edgeFunctions.yaml. Los valores se almacenan en un almacén de configuración denominado config_default:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: LOG_LEVEL
      value: DEBUG

Lea los valores de configuración en el código de función:

import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore('config_default');
const logLevel = config.get('LOG_LEVEL') || 'info';

Variables secretas de funciones Edge function-secrets

Se hace referencia a los secretos, no se almacenan, en edgeFunctions.yaml. El campo value debe señalar a un secreto de Cloud Manager mediante la sintaxis ${{SECRET_REFERENCE}}. Defina primero el secreto subyacente en Cloud Manager; consulte Variables secretas de Cloud Manager.

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  secrets:
    - key: API_TOKEN
      value: ${{API_TOKEN_SECRET}}

Recupere secretos en su código de función utilizando el asistente SecretStoreManager de la plantilla:

import { SecretStoreManager } from "./lib/config";

const apiToken = await SecretStoreManager.getSecret('API_TOKEN');

KVStore de funciones Edge function-kv-store

Las funciones de Edge pueden leer y escribir datos de valor clave arbitrarios en tiempo de ejecución a través de un KVStore. Para habilitarlo, establezca kvs: true en edgeFunctions.yaml:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  kvs: true

Esto aprovisiona un KVStore vacío denominado kv_default. Rellénelo en tiempo de ejecución desde el código de función perimetral mediante la API de KVStastly:

import { KVStore } from "fastly:kv-store";

const kv = new KVStore('kv_default');

// Read a value
const entry = await kv.get('visit-count');
const count = entry ? Number(await entry.text()) : 0;

// Write a value
await kv.put('visit-count', String(count + 1));

Registro logging

Las funciones de AEM Edge se integran con la función Reenvío de registros de AEM. Crear un archivo de logForwarding.yaml junto con su edgeFunctions.yaml:

kind: "LogForwarding"
version: "1"
metadata:
  envTypes: ["rde", "dev", "stage", "prod"]
data:
  splunk:
    default:
      enabled: true
      host: "splunk-host.example.com"
      token: "${{SPLUNK_TOKEN}}"
      index: "AEMaaCS"

Utilice el registrador en el código de función para escribir entradas de registro estructuradas:

import { Logger } from "fastly:logger";

const logger = new Logger("customerSplunk");
logger.log(JSON.stringify({
  method: event.request.method,
  url: event.request.url
}));