Verwenden von Konfigurationen und Geheimnissen mit Edge-Funktionen

Erfahren Sie, wie Sie nicht vertrauliche Konfigurationen und vertrauliche Geheimnisse über edgeFunctions.yaml an eine AEM Edge-Funktion übergeben und in Ihrem Code lesen.

Konfigurationen vs. Geheimnisse

Sowohl configs als auch secrets sind Schlüssel/Wert-Paare, die Sie Ihrer AEM Edge-Funktion bereitstellen.

Der Unterschied besteht darin, wo der Wert lebt und wie sensibel er ist.

Wo Sie Konfigurationen und Geheimnisse deklarieren

Deklarieren Sie beide unter data in edgeFunctions.yaml als gleichrangige Elemente von functions. Sie sind nicht unter einer einzelnen Funktion verschachtelt.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: TRIPS_API_BASE_URL
      value: "https://api.example.com/trips"
    - key: ADVENTURE_CACHE_TTL_SECONDS
      value: "300"
  secrets:
    - key: TRIPS_API_TOKEN
      value: ${{WKND_TRIPS_API_TOKEN}}

Bei Schlüsselnamen wird zwischen Groß- und Kleinschreibung unterschieden. Der hier deklarierte key ist derselbe Name, den Ihr Code zur Laufzeit liest.

Alle unterstützten Eigenschaften finden Sie unter Funktionen deklarieren.

Verwenden von Konfigurationen

Konfigurationen enthalten nicht vertrauliche Werte, die je nach Umgebung variieren. Konfigurationswerte sind immer Zeichenfolgen. Wandeln Sie sie also um, wenn Sie eine Zahl oder einen booleschen Wert benötigen.

Lesen von Konfigurationen im Code

Öffnen Sie den config_default Store und rufen Sie dann get() mit dem deklarierten Schlüssel auf. Der Aufruf erfolgt synchron.

// src/index.js or handler file
import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore("config_default");

// read a config value (always a string)
const apiBaseUrl = config.get("TRIPS_API_BASE_URL");

// cast to a number, with a fallback if the key is missing
const ttlSeconds = Number(config.get("ADVENTURE_CACHE_TTL_SECONDS") || "300");

Verwenden von geheimen Daten

Geheime Daten enthalten vertrauliche Werte, z. B. ein API-Token. Der Wert bleibt in einem Cloud Manager-Geheimnis. Ihr edgeFunctions.yaml verweist mit der ${{SECRET_NAME}} Syntax darauf, sodass der Wert nie in Git angezeigt wird.

Zwei Namen sind beteiligt, und sie sind absichtlich unterschiedlich.

In diesem Beispiel werden ein Schlüssel und ein Geheimnis verwendet, das Muster für AEM as a Cloud Service. In Edge Delivery Services wiederholen Sie das Muster einmal pro Site, da eine Konfigurations-Pipeline alle drei Sites bedient.

Geheime Daten in AEM as a Cloud Service hinzufügen

Definieren Sie das Cloud Manager-Geheimnis und führen Sie die Konfigurations-Pipeline aus, bevor Sie es in Ihrer AEM Edge-Funktion verwenden. Jede Umgebung (RDE, Dev, Staging, Prod) verfügt über eine eigene Registerkarte „Konfiguration“, sodass ein Geheimnis, das Sie der Entwicklung hinzufügen, erst dann in der Staging- oder Produktionsumgebung vorhanden ist, wenn Sie sie dort hinzufügen.

Geheime Daten in Edge Delivery Services hinzufügen

Edge Delivery Services verfügt über eine Konfigurations-Pipeline pro Programm, nicht eine pro Site. Sie stellt für das gesamte Programm eine einzige edgeFunctions.yaml bereit, die von jeder Site gemeinsam genutzt wird, anstatt eine separate Datei pro Site zu erstellen.

Die Entwicklungs-, Staging- und Produktions-Sites nutzen alle diese eine Pipeline, sodass Sie nicht denselben Variablennamen dreimal mit drei verschiedenen Werten hinzufügen können und sich nicht darauf verlassen können, dass eine verzweigungsspezifische edgeFunctions.yaml die richtige auswählt.

Stellen Sie jeder Variablen das Präfix ihrer Site voran, sodass die drei Sites nie miteinander kollidieren, z. B. DEV_TRIPS_API_TOKEN, STAGE_TRIPS_API_TOKEN und MAIN_TRIPS_API_TOKEN. Deklarieren Sie alle drei Elemente im selben edgeFunctions.yaml und wählen Sie dann zur Laufzeit im Code das richtige Element aus.

# config/edgeFunctions.yaml
secrets:
  - key: TRIPS_API_TOKEN_DEV
    value: ${{DEV_TRIPS_API_TOKEN}}
  - key: TRIPS_API_TOKEN_STAGE
    value: ${{STAGE_TRIPS_API_TOKEN}}
  - key: TRIPS_API_TOKEN_MAIN
    value: ${{MAIN_TRIPS_API_TOKEN}}

Die AEM Edge-Funktion muss basierend auf der Site, die sie derzeit bereitstellt, entscheiden, welcher Schlüssel zur Laufzeit gelesen werden soll. Im nächsten Abschnitt wird die Suche angezeigt.

Lesen von Geheimnissen im Code

Lesen Sie die geheimen Daten zur Laufzeit über den SecretStoreManager-Helfer, den das Textbausteinmodell in src/lib/config.js bereitstellt. Es liest sich aus dem secret_default. Der Aufruf erfolgt auf beiden Plattformen asynchron, aber die nachgeschlagene Taste ist unterschiedlich.

Auf AEM as a Cloud Service ist der Schlüssel fest, da jede Umgebung ihr eigenes Geheimnis hinter demselben Schlüsselnamen hat:

// src/index.js or handler file
import { SecretStoreManager } from "./lib/config";

const token = await SecretStoreManager.getSecret("TRIPS_API_TOKEN");
if (!token) {
  throw new Error("TRIPS_API_TOKEN is not configured");
}

Erstellen Sie auf Edge Delivery Services zuerst den Schlüssel der aktuellen Site, da ein freigegebener edgeFunctions.yaml einen separaten Schlüssel pro Site deklariert:

// src/index.js or handler file
import { SecretStoreManager } from "./lib/config";

const site = getCurrentSite(); // for example, "DEV", "STAGE", or "MAIN" based on the origin header
const token = await SecretStoreManager.getSecret(`TRIPS_API_TOKEN_${site}`);
if (!token) {
  throw new Error(`TRIPS_API_TOKEN_${site} is not configured`);
}

Sobald Sie das Token haben, verwenden Sie es in Ihrer ausgehenden Anfrage auf beiden Plattformen auf die gleiche Weise:

// use the token in an outbound request, never in a response to the client
const request = new Request("https://api.example.com/trips", {
  headers: { Authorization: `Bearer ${token}` },
});

Behalten Sie das Geheimnis in der AEM Edge-Funktion bei. Kehren Sie nicht zum Client zurück oder protokollieren Sie ihn nicht.

Richtlinien

Zusätzliche Ressourcen