Fonctions d’AEM Edge aem-edge-functions

AEM Edge Functions vous permet d’exécuter JavaScript au niveau de la couche CDN, ce qui rapproche le traitement des données de l’utilisateur final. Cela réduit la latence et permet d’offrir des expériences réactives et dynamiques sans aller-retour vers votre origine.

Cas d’utilisation courants :

AEM Edge Functions est compatible avec la pile Java Edge Delivery Services et AEM as a Cloud Service, pour les clients AEM Sites.

Suivez ce tutoriel pour une présentation concrète des variations de la pile Java Edge Delivery Services et AEM as a Cloud Service.

Principaux avantages key-benefits

Conditions préalables prerequisites

Configuration setup

Installation de l’interface de ligne de commande Adobe install-adobe-cli

Installez l’interface de ligne de commande Adobe Developer (aio) :

npm install -g @adobe/aio-cli

Installez le plug-in des fonctions AEM Edge :

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

Authentifiez et configurez le plug-in pour votre environnement :

aio login
aio aem edge-functions setup

La commande de configuration vous invite à vous connecter, puis à sélectionner l’environnement AEM sur lequel vous souhaitez utiliser les fonctions AEM Edge.

Clonez la plaque chauffante boilerplate

Copiez le aem-edge-functions-boilerplate dans votre propre référentiel, puis installez les dépendances :

npm install

Enregistrement De Votre Fonction AEM Edge register-your-function

Les fonctions AEM Edge sont déclarées dans un fichier de configuration YAML et déployées via le pipeline de configuration Cloud Manager.

​1. Configuration d’un pipeline de configuration configuration-pipeline

Avant de créer une fonction Edge, assurez-vous que dans Cloud Manager, un pipeline de configuration existe pour votre environnement (si vous utilisez la pile Java AEM) ou qu’il existe un pipeline Edge Delivery Services si votre projet est implémenté avec Edge Delivery Services. Voir Utiliser des pipelines de configuration pour plus d’informations sur la configuration des pipelines.

​2. Déclaration De Votre Fonction Edge declare-functions

Créez un fichier nommé edgeFunctions.yaml dans votre répertoire de configuration :

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

Les environnements Java-stack possèdent 1 fonction Edge et les implémentations Edge Delivery Services ont 3 fonctions Edge. Les clés de niveau supérieur facultatives sont les suivantes :

Consultez la configuration avancée telle que configs, secrets et kvs dans la section de configuration avancée ci-dessous.

​3. Déploiement de la fonction Edge via Cloud Manager deploy-functions-via-cm

À l’aide de Cloud Manager, déployez le pipeline de sorte que la fonction Edge soit enregistrée sur le réseau CDN.

Créer, créer et déployer du code de fonction AEM Edge build-deploy

Création author

Écrivez votre logique commerciale de code de fonction Edge, en utilisant le dossier src du modèle standard comme point de départ.

Créer build

Regroupez le code de votre fonction Edge pour le déploiement :

aio aem edge-functions build

Déployer deploy

Déployez le code de fonction Edge empaqueté sur la fonction Edge nommée. L’argument function-name doit correspondre à la valeur name dans edgeFunctions.yaml :

aio aem edge-functions deploy <function-name>

Tester test

Assurez-vous que la fonction Edge fonctionne comme prévu. Vous pouvez le tester à l’adresse :

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

Par exemple, pour la Java-stack AEM :

edgefunction-pXXXXX-eYYYYY-my-edge-function.adobeaemcloud.com/weather

ou pour Edge Delivery Services:

edgefunction-pXXXXX-dYYYYY-my-edge-function.adobeaemcloud.com/weather

Ce domaine avec le préfixe edgefunction est uniquement destiné au débogage, mais ne doit pas être référencé pour le trafic en direct car il ne s’agit pas d’un nom stable. Pour déterminer la valeur de AAAA, consultez la sortie de la commande de déploiement .

Connecter au flux de diffusion de contenu wiring

Le trafic des fonctions Edge doit être envoyé au domaine du site web, qui est généralement un domaine personnalisé pour la pile Java AEM, et doit être un domaine personnalisé pour Edge Delivery Services Sites.

​1. Définir des sélecteurs d’origine origin-selectors

Les fonctions Edge sont appelées en leur acheminant le trafic du réseau CDN via les règles du sélecteur d’origine. Ajoutez les éléments suivants à votre fichier de configuration cdn.yaml (ou créez-en un s’il n’existe pas) :

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

Les règles du sélecteur d’origine vous permettent d’acheminer le trafic vers vos fonctions Edge en fonction de toute condition disponible dans le moteur de règles du réseau CDN, telle qu’un chemin, un domaine ou un en-tête de requête spécifique. Plusieurs règles peuvent acheminer différents chemins vers la même fonction Edge. Voir Sélecteurs d’origine pour connaître la syntaxe complète des règles.

​2. Déploiement de la configuration deploy-to-cdn

Validez le cdn.yaml dans votre référentiel Git Cloud Manager et déclenchez le pipeline de configuration. Une fois le pipeline terminé avec succès, vos points d’entrée de fonction Edge sont disponibles à l’adresse :

Pour le débogage, vous pouvez référencer la fonction Edge au publish-pXXXXX-eYYYYY.adobeaemcloud.com du domaine (pour la pile Java AEM) ou publish-pXXXXX-dYYYYY.adobeaemcloud.com (pour les sites Edge Delivery Services). N’utilisez pas ce domaine en exploitation, car il ne s’agit pas d’un nom stable. Pour déterminer la valeur de AAAA, consultez la sortie de la commande de déploiement .

Développement local local-development

Exécuter localement local-run

Démarrez un serveur de développement local à l’adresse http://127.0.0.1:7676 :

aio aem edge-functions serve

Voir cette documentation Compute JavaScript pour plus d’informations sur ce que prend en charge l’exécution locale.

Tester test-localdev

Exécutez la suite de tests avec Mocha :

npm run test

Débogage à distance remote-debugging

Le réseau CDN géré par Adobe n’expose pas de débogueur distant, mais expose la diffusion en continu du journal. Suivez les logs pour qu’une fonction déployée reçoive console.log sortie directement dans votre terminal :

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

Mise en cache et purge du cache caching

Les fonctions Edge peuvent réduire considérablement la charge d’origine et améliorer les temps de réponse en mettant en cache les données Edge. Cependant, la mise en cache nécessite une conception intentionnelle, en particulier dans les fonctions Edge où deux couches de cache indépendantes sont impliquées :

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

Avant de configurer la mise en cache, examinez le comportement de votre contenu :

Comme le réseau CDN et le cache de récupération interne de la fonction Edge fonctionnent indépendamment, toute modification des données sous-jacentes nécessite l’invalidation délibérée des couches des deux. La compréhension de cette architecture est essentielle pour une gestion fiable du cache.

Pour obtenir des conseils techniques détaillés sur la configuration du comportement de mise en cache, le contrôle des durées de vie du cache, l’utilisation de clés de substitution et la purge du contenu mis en cache, voir ​ Mise en cache dans les fonctions AEM Edge ​.

Limites limitations

Nbre max. d’appels de récupération sortante par appel max-fetch-calls

Les fonctions AEM Edge appliquent une limite stricte de 32 requêtes principales par exécution (c’est-à-dire par requête entrante gérée par votre fonction). Une fois cette limite atteinte, tous les autres appels fetch() échouent avec l’erreur suivante :

Requested backend named '…' does not exist

Lorsque cette erreur s’affiche et que votre configuration d’origine est correcte, la cause la plus probable est que le quota de requêtes du serveur principal par appel a été épuisé. Consultez Limites des ressources du calcul rapide pour obtenir la liste complète des limites de la plateforme.

Configuration avancée des fonctions Edge advanced-function-configuration

Origines origins

Par défaut, les fonctions Edge peuvent être extraites de n’importe quelle origine. Pour restreindre une fonction à un ensemble défini d’origines, déclarez-les sous origins dans edgeFunctions.yaml :

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

Référencez l’origine nommée dans le code de votre fonction à l’aide de l’option de récupération backend :

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

Variables de configuration de la fonction Edge function-configuration

Exposez les variables d’environnement à vos fonctions à l’aide de la clé configs dans edgeFunctions.yaml. Les valeurs sont stockées dans un magasin de configurations nommé config_default :

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

Lisez les valeurs de configuration dans votre code de fonction :

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

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

Variables secrètes de fonction Edge function-secrets

Les secrets sont référencés, et non stockés, dans edgeFunctions.yaml. Le champ value doit pointer vers un secret Cloud Manager en utilisant la syntaxe ${{SECRET_REFERENCE}}. Définissez d’abord le secret sous-jacent dans Cloud Manager — consultez Variables du secret Cloud Manager.

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

Récupérez les secrets du code de votre fonction à l’aide de l’assistant SecretStoreManager à partir de la page standard :

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

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

Boutique KV de fonction Edge function-kv-store

Les fonctions Edge peuvent lire et écrire des données de valeur-clé arbitraires au moment de l’exécution via un magasin KV. Pour l’activer, définissez kvs: true dans edgeFunctions.yaml :

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

Cela fournit un magasin KV vide nommé kv_default. Renseignez-le au moment de l’exécution à partir du code de votre fonction Edge à l’aide de l’API Fastly KV Store :

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));

Journalisation logging

AEM Edge Functions s’intègre à la fonctionnalité Transfert de journal AEM. Créez un fichier logForwarding.yaml avec votre 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"

Utilisez l’enregistreur dans le code de votre fonction pour écrire des entrées de journal structurées :

import { Logger } from "fastly:logger";

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