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.

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

Creare la prima funzione create-your-function

I servizi di funzioni di AEM Edge sono dichiarati in un file di configurazione YAML e distribuiti tramite la pipeline di configurazione di Cloud Manager.

​1. Configurare una pipeline di configurazione configuration-pipeline

Prima di creare una funzione Edge, accertati che esista una pipeline di configurazione per l’ambiente in Cloud Manager. In caso contrario, crea prima una pipeline di configurazione.

​2. Dichiarare i servizi di funzione di Edge declare-services

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

kind: "EdgeFunctions"
version: "1"
data:
  services:
    - name: first-function
    - name: second-function
    # Uncomment to enable secrets
    # secrets:
    #   - key: API_TOKEN
    #     value: ${{ API_TOKEN_SECRET }}

La configurazione supporta fino a tre servizi. Le chiavi di primo livello sono:

​3. Aggiungi regole selettore origine CDN cdn-routing

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-to-first-function
        when: { reqProperty: path, equals: "/weather" }
        action:
          type: selectAemOrigin
          originName: edgefunction-first-function
      - name: route-to-second-function
        when: { reqProperty: path, equals: "/hello-world" }
        action:
          type: selectAemOrigin
          originName: edgefunction-second-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. Consulta Selettori origine per la sintassi completa della regola.

​4. Distribuire la configurazione deploy-configuration

Esegui il commit di edgeFunctions.yaml e 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:

dove pXXXXX-eYYYYY sono le coordinate dell’ambiente. Se è configurato un dominio personalizzato, le funzioni sono raggiungibili anche in questi percorsi di dominio (ad esempio, example.com/weather).

Creare e distribuire codice funzione di AEM Edge build-deploy

Build build

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

aio aem edge-functions build

Distribuzione deploy

Distribuisci il pacchetto generato in un servizio di funzioni edge denominato. L’argomento function-name deve corrispondere al valore name in edgeFunctions.yaml:

aio aem edge-functions deploy <function-name>

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

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

Ogni chiamata alla funzione Edge viene eseguita all’interno di una sandbox con limiti di risorse imposti dalla piattaforma di calcolo sottostante.

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.

Riferimento configurazione configuration-reference

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

Configurazione servizio service-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:

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

Segreti di servizio service-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.

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

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