Usar configuraciones y secretos con funciones de Edge

Aprenda a pasar configuraciones no confidenciales y secretos confidenciales a una función de AEM Edge a través de edgeFunctions.yaml y a leerlos en su código.

Configuraciones frente a secretos

Tanto configs como secrets son pares clave/valor que usted expone a su función Edge de AEM.

La diferencia es dónde vive el valor y lo sensible que es.

Donde se declaran configuraciones y secretos

Declarar a ambos menores de data en edgeFunctions.yaml, como hermanos de functions. No están anidadas en una función individual.

# 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}}

Los nombres de clave distinguen entre mayúsculas y minúsculas. El key que declara aquí tiene el mismo nombre que su código lee durante la ejecución.

Para ver todas las propiedades compatibles, consulte Declarar funciones.

Usar configuraciones

Las configuraciones contienen valores no confidenciales que varían según el entorno. Los valores de configuración siempre son cadenas, por lo que debe convertirlos cuando necesite un número o un valor booleano.

Leer configuraciones en el código

Abra el almacén config_default y luego llame a get() con la clave que declaró. La llamada es sincrónica.

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

Usar secretos

Los secretos contienen valores confidenciales, como un token de API. El valor permanece en un secreto de Cloud Manager. Su edgeFunctions.yaml hace referencia a él con la sintaxis ${{SECRET_NAME}}, por lo que el valor nunca aparece en Git.

Hay dos nombres involucrados, y son diferentes a propósito.

Este ejemplo utiliza una clave y un secreto, el patrón para AEM as a Cloud Service. En Edge Delivery Services, repita el patrón una vez por sitio, ya que una canalización de configuración sirve a los tres sitios.

Añadir el secreto en AEM as a Cloud Service

Defina el secreto de Cloud Manager y ejecute la canalización de configuración antes de utilizarlo en la función de Edge de AEM. Cada entorno (RDE, Dev, Stage, Prod) tiene su propia pestaña Configuración, por lo que un secreto que añada a Dev no existe en Stage o Prod hasta que lo añada allí también.

Añadir el secreto en Edge Delivery Services

Edge Delivery Services tiene una canalización de configuración por programa, no una por sitio. Implementa un único edgeFunctions.yaml para todo el programa, compartido por cada sitio, en lugar de un archivo independiente por sitio.

Los sitios de Desarrollo, Ensayo y Producción comparten esa canalización, por lo que no puede agregar el mismo nombre de variable tres veces con tres valores diferentes y no puede confiar en que un edgeFunctions.yaml específico de la rama elija el correcto.

Agregue a cada nombre de variable su sitio para que los tres sitios nunca entren en conflicto, por ejemplo DEV_TRIPS_API_TOKEN, STAGE_TRIPS_API_TOKEN y MAIN_TRIPS_API_TOKEN. Declare los tres en el mismo edgeFunctions.yaml y, a continuación, permita que el código elija el correcto durante la ejecución.

# 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}}

La función Edge de AEM debe decidir qué clave leer durante la ejecución, en función del sitio al que sirve actualmente. La siguiente sección muestra la búsqueda.

Leer secretos en código

Lea el secreto durante la ejecución a través del asistente SecretStoreManager que proporciona la repetidor en src/lib/config.js. Se lee del almacén secret_default. La llamada de es asincrónica en ambas plataformas, pero la clave que busca difiere.

En AEM as a Cloud Service, la clave está corregida, ya que cada entorno tiene su propio secreto detrás del mismo nombre de clave:

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

En Edge Delivery Services, genere primero la clave del sitio actual, ya que uno de los edgeFunctions.yaml compartidos declara una clave independiente por sitio:

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

Una vez que tenga el token, utilícelo en la solicitud saliente del mismo modo en ambas plataformas:

// 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}` },
});

Guarde el secreto dentro de la función Edge de AEM. No lo devuelva al cliente ni lo registre.

Directrices

Recursos adicionales