Erstellen eines API-Endpunkts mit Edge-Funktionen

Eine AEM Edge-Funktion ist ein JavaScript-Modul, das auf Adobe CDN (Fastly Compute) ausgeführt wird. Sie machen sie als einen oder mehrere) HTTP Endpunkte verfügbar, indem Sie CDN-Ursprungs-Selektorregeln mit einem Fetch-Ereignis-Handler in Ihrem Code verknüpfen.

Auf dieser Seite werden der Vertrag und die Schlüsseldateien behandelt. Sie können eine beliebige Logik in den Handler schreiben, einschließlich ausgehender fetch() an andere Systeme. Halten Sie den Handler schnell und kurzlebig, damit er zur Edge-Laufzeit passt.

Voraussetzungen

Informationen zur Ersteinrichtung finden Sie unter Einrichten auf AEM as a Cloud Service oder Einrichten auf Edge Delivery Services.

Wie eine HTTP-Anfrage Ihren Code erreicht

Eine Anfrage erreicht Ihre AEM Edge-Funktion in zwei Schritten: Der CDN-Ursprüngsselektor leitet den Endpunkt an die Funktion weiter und Ihr Fetch-Ereignis-Handler wird ausgeführt.

Browser → CDN origin selector (cdn.yaml) → AEM Edge Function (index.js) → Your handler logic (optional fetch to other systems)

Der Ursprungsselektor und der Funktionsname müssen aufeinander abgestimmt sein. Wenn edgeFunctions.yaml my-edge-function deklariert, verwendet die Ursprungsauswahl edgefunction-my-edge-function in cdn.yaml.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function #<name-of-the-function>

# config/cdn.yaml (origin selector excerpt)
kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-status-endpoint-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/status" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: false # false to use the CDN cache for this path
      - name: route-my-api-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/my-api" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: true # true to bypass the CDN cache for this path

Jeder Endpunkt benötigt in cdn.yaml eine eigene Ursprungsauswahlregel. Eine AEM Edge-Funktion kann mehrere Endpunkte bereitstellen, aber das CDN muss jeden Pfad an diese Funktion weiterleiten. Legen Sie skipCache: false fest, um das CDN-Caching für stabile Antworten zu ermöglichen, oder skipCache: true Sie den CDN-Cache für dynamische oder personalisierte Antworten umgehen.

Informationen zu den Optionen für die Herkunftsselektoren finden Sie unter Herkunftsselektoren.

Anfragen verarbeiten

Jede AEM Edge-Funktion registriert einen Abruf-Ereignishandler. Adobe CDN ruft diesen Handler für jede übereinstimmende Anfrage auf. Der Handler liest die eingehenden Request, führt die Logik aus und gibt eine Response zurück.

// src/index.js
import { myApiHandler } from "./my-api.js";
import * as response from "./lib/response.js";

// entry point for the AEM Edge Function
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  // event.request is a standard Fetch API Request (method, URL, headers, body)
  const req = event.request;
  const url = new URL(req.url);

  try {
    // endpoint matching
    if (url.pathname === "/status" && req.method === "GET") {
      return new Response("OK", { status: 200 });
    } else if (url.pathname === "/my-api" && req.method === "GET") {
      return await myApiHandler(req, event.client);
    }
    // add more endpoints here

    return response.notFound();
  } catch (err) {
    console.log(err);
    return response.error();
  }
}

Wichtigste Punkte:

Endpunkt, der in index.js lebt. Wenn Ihre Endpunkte wachsen, verschieben Sie die Handler-Logik in separate Dateien und importieren Sie sie, wie my-api.js Beispiel oben gezeigt. Unter Bereitstellen mehrerer Endpunkte mit Edge-Funktionen finden Sie Muster, während Ihre API-Oberfläche erweitert wird.

Handler-Logik schreiben

Innerhalb jedes Endpunkt-Handlers können Sie jeden JavaScript ausführen, der zur Edge-Laufzeit passt. Halten Sie die Arbeit schnell und kurzlebig. Bevorzugen Sie leichte Transformationen, Geo-Suchen, einfache JSON- oder HTML-Antworten und kleine Aggregationen gegenüber langwierigen oder umfangreichen Datenverarbeitungsvorgängen.

Eine minimale Antwort sieht wie folgt aus:

if (url.pathname === "/status" && req.method === "GET") {
  return new Response("OK", { status: 200 });
}

Sie können JSON, HTML oder Nur-Text zurückgeben. Legen Sie Kopfzeilen auf der Response fest, um den Inhaltstyp und die Zwischenspeicherung zu steuern:

return new Response(JSON.stringify({ status: "ok" }), {
  status: 200,
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "public, max-age=300",
  },
});

Wenn Sie Daten aus einem anderen System benötigen, rufen Sie es mit fetch() auf. Beibehalten von Anmeldeinformationen in der AEM Edge-Funktion. Geben Sie keine Geheimnisse in Client-JavaScript an.

// src/my-api.js
async function myApiHandler(req, client) {
  const backendRequest = new Request("https://api.example.com/data");

  // optionally, you can add headers to the request
  // backendRequest.headers.set("Authorization", `Bearer <your-access-token>`);

  const backendResponse = await fetch(backendRequest);

  if (!backendResponse.ok) {
    return new Response("Backend error", { status: 502 });
  }

  const data = await backendResponse.json();

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "max-age=300",
    },
  });
}

export { myApiHandler };

Ausgehende fetch()-Aufrufe folgen in der Regel diesem Muster:

Es gelten Plattformbeschränkungen. Jeder Aufruf unterstützt bis zu 32 ausgehende Abrufaufrufe. Informationen zum Cacheverhalten bei Abrufaufrufen finden Sie unter Caching in AEM Edge Functions.

Weitere Code-Beispiele

Vollständige Arbeitsbeispiele finden Sie im AEM Edge Functions-Textbaustein:

Zusätzliche Ressourcen