Funzioni di AEM Edge aem-edge-functions

Le funzioni Edge di AEM consentono di eseguire JavaScript a livello di CDN, avvicinando l’elaborazione dei dati all’utente finale. Questo riduce la latenza e consente esperienze dinamiche e reattive senza un viaggio di andata e ritorno all’origine.

I casi d’uso comuni includono:

Le funzioni Edge di AEM sono compatibili sia con Edge Delivery Services che con lo stack Java di AEM as a Cloud Service, per i clienti AEM Sites.

Segui questa esercitazione per una procedura dettagliata concreta per le varianti Java-stack di Edge Delivery Services e AEM as a Cloud Service.

Vantaggi principali key-benefits

Prerequisiti prerequisites

Configurazione setup

Installare Adobe CLI install-adobe-cli

Installare Adobe Developer CLI (aio):

npm install -g @adobe/aio-cli

Installa il plug-in AEM Edge Functions:

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

Autentica e configura il plug-in per l’ambiente:

aio login
aio aem edge-functions setup

Il comando di installazione richiede di accedere e quindi selezionare l’ambiente AEM in cui si desidera utilizzare le funzioni AEM Edge.

Clona la piastra boilerplate

Copia aem-edge-functions-boilerplate nel tuo archivio, quindi installa le dipendenze:

npm install

Registrare la funzione Edge di AEM register-your-function

Le funzioni Edge di AEM sono dichiarate in un file di configurazione YAML e distribuite tramite la pipeline di configurazione di Cloud Manager.

​1. Configurare una pipeline di configurazione configuration-pipeline

Prima di creare una funzione edge, accertati che in Cloud Manager esista una pipeline di configurazione per l’ambiente (se utilizzi AEM Java-stack) o una pipeline Edge Delivery Services se il progetto è implementato con Edge Delivery Services. Per informazioni sulla configurazione delle pipeline, consulta Utilizzare le pipeline di configurazione.

​2. Dichiarare la funzione Edge declare-functions

Creare un file denominato edgeFunctions.yaml nella directory di configurazione:

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

Gli ambienti Java-stack hanno 1 funzione edge e le implementazioni Edge Delivery Services hanno 3 funzioni edge. Le chiavi di primo livello facoltative sono:

Consulta la configurazione avanzata come configs, secrets e kvs nella sezione configurazione avanzata di seguito.

​3. Implementare la funzione Edge tramite Cloud Manager deploy-functions-via-cm

Utilizzando Cloud Manager, distribuisci la pipeline in modo che la funzione Edge sia registrata nella rete CDN.

Creare, generare e distribuire codice funzione di AEM Edge build-deploy

Autore author

Scrivere la logica aziendale del codice della funzione Edge utilizzando come punto di partenza la cartella src di boilerplate.

Build build

Crea un pacchetto del codice della funzione Edge per la distribuzione:

aio aem edge-functions build

Distribuzione deploy

Distribuisci il codice della funzione edge in pacchetto alla funzione edge denominata. L’argomento function-name deve corrispondere al valore name in edgeFunctions.yaml:

aio aem edge-functions deploy <function-name>

Test test

Assicurati che la funzione Edge funzioni come previsto. Puoi eseguirne il test su:

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

Ad esempio, per lo stack Java AEM:

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

o per Edge Delivery Services:

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

Il dominio con prefisso edgefunction è solo per il debug, ma non è necessario fare riferimento a per il traffico in tempo reale poiché non è garantito che sia un nome stabile. Per determinare il valore dYYYY, vedere l’output del comando deploy.

Collegamento al flusso di distribuzione dei contenuti wiring

Il traffico della funzione Edge deve essere inviato al dominio del sito Web, che in genere è un dominio personalizzato per AEM Java-stack, e deve essere un dominio personalizzato per Edge Delivery Services Sites.

​1. Definisci selettori origine origin-selectors

Le funzioni Edge vengono richiamate instradando il traffico CDN verso di esse tramite le regole del selettore di origine. Aggiungi quanto segue al file di configurazione cdn.yaml (o creane uno se non esiste):

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

Le regole del selettore di origine ti consentono di indirizzare il traffico alle funzioni edge in base a qualsiasi condizione disponibile nel motore di regole CDN, ad esempio un percorso specifico, un dominio o un’intestazione di richiesta. Più regole possono instradare percorsi diversi alla stessa funzione edge. Consulta Selettori origine per la sintassi completa della regola.

​2. Distribuire la configurazione deploy-to-cdn

Esegui il commit di cdn.yaml nell’archivio Git di Cloud Manager e attiva la pipeline di configurazione. Una volta completata correttamente la pipeline, gli endpoint della funzione Edge sono disponibili in:

Per il debug, è possibile fare riferimento alla funzione edge nel dominio publish-pXXXXX-eYYYYY.adobeaemcloud.com (per lo stack Java di AEM) o publish-pXXXXX-dYYYYY.adobeaemcloud.com (per i siti Edge Delivery Services). Non utilizzare questo dominio per l’utilizzo in produzione poiché non è garantito che sia un nome stabile. Per determinare il valore dYYYY, vedere l’output del comando deploy.

Sviluppo locale local-development

Esegui localmente local-run

Avviare un server di sviluppo locale in http://127.0.0.1:7676:

aio aem edge-functions serve

Consulta questa documentazione di Calcola JavaScript per informazioni dettagliate su ciò che supporta il runtime locale.

Test test-localdev

Esegui il gruppo di test con Mocha:

npm run test

Debug remoto remote-debugging

La rete CDN gestita di Adobe non espone un debugger remoto, ma espone il flusso del registro. Suddividi i registri di una funzione implementata per ricevere l’output console.log direttamente nel terminale:

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

Memorizzazione in cache e rimozione cache caching

Le funzioni Edge possono ridurre in modo significativo il carico dell’origine e migliorare i tempi di risposta memorizzando nella cache i dati al limite. Tuttavia, il caching richiede una progettazione intenzionale, in particolare nelle funzioni Edge in cui sono coinvolti due livelli di cache indipendenti:

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

Prima di configurare la memorizzazione in cache, considera il comportamento del contenuto:

Poiché la rete CDN e la cache di recupero interna della funzione Edge funzionano in modo indipendente, una modifica ai dati sottostanti richiede l’invalidazione intenzionale di entrambi livelli. Questa architettura è essenziale per una gestione affidabile della cache.

Per informazioni tecniche dettagliate sulla configurazione del comportamento di caching, il controllo della durata della cache, l’utilizzo di chiavi alternative e l’eliminazione del contenuto memorizzato in cache, vedere Memorizzazione in cache nelle funzioni AEM Edge.

Limitazioni limitations

Numero massimo chiamate di recupero in uscita per chiamata max-fetch-calls

Le funzioni Edge di AEM impongono un limite rigido di 32 richieste back-end per esecuzione (ovvero per richiesta in ingresso gestita dalla funzione). Una volta raggiunto questo limite, le ulteriori chiamate di fetch() non riusciranno e verrà visualizzato il seguente errore:

Requested backend named '…' does not exist

Quando visualizzi questo errore e la configurazione dell’origine è corretta, la causa più probabile è che la quota della richiesta back-end per chiamata sia stata esaurita. Per l’elenco completo dei limiti della piattaforma, vedere Limiti delle risorse Fastly Compute.

Configurazione funzione avanzata di Edge advanced-function-configuration

Origini origins

Per impostazione predefinita, le funzioni di spigolo possono essere recuperate da qualsiasi origine. Per limitare una funzione a un set definito di origini, dichiararle in origins in edgeFunctions.yaml:

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

Fai riferimento all’origine denominata nel codice della funzione utilizzando l’opzione di recupero backend:

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

Variabili di configurazione della funzione Edge function-configuration

Esporre le variabili di ambiente alle funzioni utilizzando la chiave configs in edgeFunctions.yaml. I valori sono archiviati in un archivio di configurazione denominato config_default:

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

Leggi i valori di configurazione nel codice della funzione:

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

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

Variabili segrete di funzione Edge function-secrets

In edgeFunctions.yaml sono presenti riferimenti ai segreti, non archiviati. Il campo value deve puntare a un segreto Cloud Manager utilizzando la sintassi ${{SECRET_REFERENCE}}. Definisci prima il segreto sottostante in Cloud Manager. Vedi Variabili segrete Cloud Manager.

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

Recupera i segreti nel codice della funzione utilizzando l’helper SecretStoreManager dalla boilerplate:

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

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

Archivio KV funzione Edge function-kv-store

Le funzioni di Edge possono leggere e scrivere dati arbitrari chiave-valore in fase di runtime tramite un archivio KV. Per abilitarlo, impostare kvs: true in edgeFunctions.yaml:

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

Questo esegue il provisioning di un archivio KV vuoto denominato kv_default. Compilalo in fase di runtime dal codice della funzione Edge utilizzando 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));

Registrazione logging

Le funzioni Edge di AEM si integrano con la funzione Inoltro log di AEM. Crea un file logForwarding.yaml insieme a 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"

Utilizza il logger nel codice della funzione per scrivere voci di registro strutturate:

import { Logger } from "fastly:logger";

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