AEM Edge-Funktionen aem-edge-functions

Mit den AEM Edge-Funktionen können Sie JavaScript auf CDN-Ebene ausführen, wodurch die Datenverarbeitung näher an den Endbenutzer heranrückt. Dies reduziert die Latenz und ermöglicht responsive, dynamische Erlebnisse ohne einen Roundtrip zu Ihrem Ursprung.

Häufige Anwendungsfälle umfassen:

AEM Edge-Funktionen sind sowohl mit Edge Delivery Services als auch mit dem AEM as a Cloud Service Java-Stack kompatibel.

Wichtigste Vorteile key-benefits

Voraussetzungen prerequisites

Einrichtung setup

Installieren des Adobe-CLI install-adobe-cli

Installieren des Adobe Developer-CLI (aio):

npm install -g @adobe/aio-cli

Installieren des AEM Edge-Funktions-Plug-ins:

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

Authentifizieren und Konfigurieren des Plug-ins für Ihre Umgebung:

aio login
aio aem edge-functions setup

Der Setup-Befehl fordert Sie zur Anmeldung auf und wählt dann die AEM-Umgebung aus, in der Sie AEM Edge-Funktionen verwenden möchten.

Textbaustein klonen boilerplate

Kopieren Sie aem-edge-features-boilerplate in Ihr eigenes Repository und installieren Sie dann die Abhängigkeiten:

npm install

Registrieren der AEM Edge-Funktion register-your-function

AEM Edge-Funktionen werden in einer YAML-Konfigurationsdatei deklariert und über die Cloud Manager-Konfigurations-Pipeline bereitgestellt.

​1. Einrichten einer Konfigurations-Pipeline configuration-pipeline

Stellen Sie vor dem Erstellen einer Edge-Funktion sicher, dass in Cloud Manager eine Konfigurations-Pipeline für Ihre Umgebung vorhanden ist (wenn Sie den AEM Java-Stack verwenden) oder dass eine Edge Delivery Services-Pipeline vorhanden ist, wenn Ihr Projekt mit Edge Delivery Services implementiert ist. Informationen ​ Konfigurieren der Pipelines finden ​ unter „Verwenden von-Pipelines“.

​2. Edge-Funktion deklarieren declare-functions

Erstellen Sie eine Datei mit dem Namen edgeFunctions.yaml im Konfigurationsverzeichnis:

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

Java-Stack-Umgebungen verfügen über 1 Edge-Funktion und Edge Delivery Services-Implementierungen über 3 Edge-Funktionen. Die optionalen Schlüssel der obersten Ebene sind:

Weitere Informationen zur erweiterten Konfiguration wie configs, secrets und kvs finden Sie ​ Abschnitt „Erweiterte Konfiguration weiter unten.

​3. Bereitstellen der Edge-Funktion über Cloud Manager deploy-functions-via-cm

Stellen Sie mithilfe von Cloud Manager die Pipeline bereit, damit die Edge-Funktion im CDN registriert wird.

AEM Edge-Funktions-Code erstellen, erstellen und bereitstellen build-deploy

Author author

Schreiben Sie Ihre Geschäftslogik für den Edge-FunktionsCode mithilfe des src Ordners ​Textbausteinvorlage“ als Ausgangspunkt.

Aufbauen build

Verpacken Sie Ihren Edge-Funktions-Code für die Bereitstellung:

aio aem edge-functions build

Bereitstellen deploy

Stellen Sie den gepackten Code der Edge-Funktion für die benannte Edge-Funktion bereit. Das function-name-Argument muss mit dem name in edgeFunctions.yaml übereinstimmen:

aio aem edge-functions deploy <function-name>

Testen test

Stellen Sie sicher, dass die Kantenfunktion erwartungsgemäß funktioniert. Sie können es unter folgender Adresse testen:

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

Beispielsweise für den AEM Java-Stack:

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

oder für Edge Delivery Services:

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

Diese Domain mit dem Präfix EDGEFUNCTION dient nur zur Fehlerbehebung, darf für Live-Traffic nicht referenziert werden da kein stabiler Name garantiert ist. Informationen zum Bestimmen des Werts für JJJJ finden Sie in der Ausgabe des Bereitstellungsbefehls.

In den Inhaltsbereitstellungs-Fluss integrieren wiring

Funktions-Traffic von Edge sollte an die Domain der Website gesendet werden, die normalerweise eine benutzerdefinierte Domain für den AEM Java-Stack ist, und muss eine benutzerdefinierte Domain für Edge Delivery Services Sites sein.

​1. Herkunft-Selektoren definieren origin-selectors

Edge-Funktionen werden aufgerufen, indem CDN-Traffic über Regeln der Ursprungsauswahl an sie weitergeleitet wird. Fügen Sie der cdn.yaml-Konfigurationsdatei Folgendes hinzu (oder erstellen Sie eine, falls sie nicht vorhanden ist):

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

Mit den Regeln der Ursprungsauswahl können Sie Traffic basierend auf einer in der CDN-Regel-Engine verfügbaren Bedingung, z. B. einem bestimmten Pfad, einer bestimmten Domain oder einem Anfrageheader, an Ihre Edge-Funktionen weiterleiten. Mehrere Regeln können verschiedene Pfade zu derselben Edge-Funktion routen. Siehe Ursprungs-Selektoren für die vollständige Regelsyntax.

​2. Bereitstellen der Konfiguration deploy-to-cdn

Übertragen Sie cdn.yaml in Ihr Cloud Manager-Git-Repository und Trigger in die Konfigurations-Pipeline. Sobald die Pipeline erfolgreich abgeschlossen wurde, sind Ihre Edge-Funktionsendpunkte unter verfügbar:

Zum Debuggen können Sie die Edge-Funktion auf der Domain-publish-pXXXXX-eYYYYY.adobeaemcloud.com (für den AEM Java-Stack) oder publish-pXXXXX-dYYYYY.adobeaemcloud.com (für Edge Delivery Services Sites) referenzieren. Verwenden Sie diese Domain nicht für die Verwendung in der Produktion, da sie nicht garantiert ein stabiler Name ist. Informationen zum Bestimmen des Werts für JJJJ finden Sie in der Ausgabe des Bereitstellungsbefehls.

Lokale Entwicklung local-development

Lokal ausführen local-run

Starten Sie einen lokalen Entwicklungs-Server unter http://127.0.0.1:7676:

aio aem edge-functions serve

In dieser Compute JavaScript-Dokumentation finden Sie Details dazu, was die lokale Laufzeit unterstützt.

Testen test-localdev

Ausführen der Test-Suite mit Mokka:

npm run test

Remote-Debugging remote-debugging

Das von Adobe verwaltete CDN stellt keinen Remote-Debugger bereit, stellt jedoch Protokoll-Streaming bereit. Verfolgen Sie die Protokolle für eine bereitgestellte Funktion, um console.log Ausgabe direkt in Ihrem Terminal zu erhalten:

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

Caching und Cache-Bereinigung caching

Edge-Funktionen können die Ursprungslast erheblich reduzieren und die Antwortzeiten verbessern, indem Daten am Edge zwischengespeichert werden. Für das Caching ist jedoch ein absichtliches Design erforderlich - insbesondere in Edge-Funktionen bei denen (zwei unabhängige Cache Ebenen) involviert sind:

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

Bevor Sie das Caching konfigurieren, überlegen Sie, wie sich Ihr Inhalt verhält:

Da das CDN und der interne Abrufcache der Edge-Funktion unabhängig voneinander arbeiten, erfordert eine Änderung der zugrunde liegenden Daten die bewusste Invalidierung beider Ebenen. Das Verständnis dieser Architektur ist für eine zuverlässige Cache-Verwaltung unerlässlich.

Detaillierte technische Anleitungen zum Konfigurieren des Caching-Verhaltens, zum Steuern der Cache-Lebensdauer, zum Verwenden von Ersatzschlüsseln und zum Bereinigen von zwischengespeicherten Inhalten finden Sie unter Caching in AEM Edge Functions.

Einschränkungen limitations

Maximal ausgehende Abrufaufrufe pro Aufruf max-fetch-calls

AEM Edge-Funktionen erzwingen eine feste Grenze von 32 Backend-Anfragen pro Ausführung (d. h. pro eingehender Anfrage, die von Ihrer Funktion verarbeitet wird). Sobald diese Grenze erreicht ist, schlagen alle weiteren fetch()-Aufrufe mit dem folgenden Fehler fehl:

Requested backend named '…' does not exist

Wenn dieser Fehler angezeigt wird und Ihre ursprüngliche Konfiguration korrekt ist, besteht die wahrscheinlichste Ursache darin, dass das Kontingent für die Backend-Anfrage pro Aufruf ausgeschöpft wurde. Siehe Fastly Compute Resource Limits für die vollständige Liste der Platform Limits.

Erweiterte Edge-Funktionskonfiguration advanced-function-configuration

Ursprünge origins

Standardmäßig können Edge-Funktionen aus jedem beliebigen Ursprung abgerufen werden. Um eine Funktion auf einen definierten Satz von Ursprüngen zu beschränken, deklarieren Sie sie unter origins in edgeFunctions.yaml:

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

Referenzieren Sie die benannte Herkunft in Ihrem Funktionscode mithilfe der backend-Fetch-Option:

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

Edge-Funktionskonfigurationsvariablen function-configuration

Offenlegung von Umgebungsvariablen für Ihre Funktionen mithilfe der configs in edgeFunctions.yaml. Die Werte werden in einem Konfigurationsspeicher mit dem Namen config_default gespeichert:

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

Lesen Sie die Konfigurationswerte im Funktionscode:

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

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

Edge-Funktionsgeheimnis-Variablen function-secrets

Geheimnisse werden in edgeFunctions.yaml referenziert, nicht gespeichert. Das value muss mithilfe der ${{SECRET_REFERENCE}} auf geheime Daten vom Typ Cloud Manager verweisen. Definieren Sie zunächst das zugrunde liegende Geheimnis in Cloud Manager - siehe Cloud Manager-Geheimnisvariablen.

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

Abrufen von geheimen Daten im Funktionscode mithilfe des SecretStoreManager Helpers aus dem Textbaustein:

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

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

Edge-Funktions-KV-Speicher function-kv-store

Edge-Funktionen können beliebige Schlüssel-Wert-Daten zur Laufzeit über einen KV-Speicher lesen und schreiben. Um sie zu aktivieren, legen Sie kvs: true in edgeFunctions.yaml fest:

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

Dadurch wird ein leerer KV-Speicher mit dem Namen kv_default bereitgestellt. Füllen Sie es zur Laufzeit aus Ihrem Edge-Funktions-Code mithilfe der Fastly KV Store-API:

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

Protokollierung logging

AEM Edge-Funktionen sind mit der Funktion AEM- integriert. Erstellen Sie eine logForwarding.yaml Datei zusammen mit Ihrem 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"

Verwenden Sie den Logger in Ihrem Funktionscode, um strukturierte Protokolleinträge zu schreiben:

import { Logger } from "fastly:logger";

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