Utilizzare configurazioni e segreti con le funzioni di Edge

Scopri come passare configs e secrets non sensibili a una funzione Edge di AEM tramite edgeFunctions.yaml e leggerli nel codice.

Configurazioni e segreti

Sia configs che secrets sono coppie chiave/valore esposte alla funzione Edge di AEM.

La differenza sta nel punto in cui si trova il valore e nella sua sensibilità.

Dove si dichiarano configurazioni e segreti

Dichiarare entrambi in data in edgeFunctions.yaml, come pari livello di functions. Non sono nidificati sotto una singola funzione.

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

I nomi delle chiavi fanno distinzione tra maiuscole e minuscole. Il key dichiarato è lo stesso nome che il codice legge in fase di esecuzione.

Per tutte le proprietà supportate, vedere Dichiarare le funzioni.

Utilizzare le configurazioni

Le configurazioni contengono valori non sensibili che variano a seconda dell’ambiente. I valori di configurazione sono sempre stringhe, quindi esegui il cast quando hai bisogno di un numero o booleano.

Leggi configurazioni nel codice

Apri l’archivio config_default, quindi chiama get() con la chiave dichiarata. La chiamata è sincrona.

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

Usa segreti

I segreti contengono valori sensibili, ad esempio un token API. Il valore rimane in un segreto Cloud Manager. edgeFunctions.yaml vi fa riferimento con la sintassi ${{SECRET_NAME}}, pertanto il valore non viene mai visualizzato in Git.

Sono coinvolti due nomi, che sono diversi di proposito.

In questo esempio viene utilizzato un tasto e un segreto, il pattern per AEM as a Cloud Service. In Edge Delivery Services, ripetete il pattern una volta per sito, poiché una pipeline di configurazione serve tutti e tre i siti.

Aggiungi il segreto su AEM as a Cloud Service

Definisci il segreto Cloud Manager ed esegui la pipeline di configurazione prima di utilizzarlo nella funzione Edge di AEM. Ogni ambiente (RDE, Dev, Stage, Prod) dispone di una propria scheda Configurazione, pertanto un segreto aggiunto a Dev non esiste in Stage o Prod finché non viene aggiunto anche in quest’ultimo.

Aggiungi il segreto su Edge Delivery Services

Edge Delivery Services dispone di una pipeline di configurazione per programma, non una per sito. Distribuisce un singolo edgeFunctions.yaml per l’intero programma, condiviso da ogni sito, anziché un file separato per sito.

I siti di sviluppo, staging e produzione condividono tutti questa pipeline, pertanto non è possibile aggiungere lo stesso nome di variabile tre volte con tre valori diversi e non è possibile fare affidamento su un edgeFunctions.yaml specifico per il ramo per scegliere quello giusto.

Aggiungi il prefisso del nome di ciascuna variabile al relativo sito in modo che i tre siti non si scontrino mai, ad esempio DEV_TRIPS_API_TOKEN, STAGE_TRIPS_API_TOKEN e MAIN_TRIPS_API_TOKEN. Dichiara tutti e tre nello stesso edgeFunctions.yaml, quindi lascia che il codice scelga quello giusto in fase di esecuzione.

# 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 funzione Edge di AEM deve decidere quale chiave leggere in fase di runtime, in base al sito che sta attualmente servendo. La sezione successiva mostra la ricerca.

Leggi i segreti nel codice

Leggere il segreto in fase di esecuzione tramite l’helper SecretStoreManager fornito dalla boilerplate in src/lib/config.js. Legge dall’archivio secret_default. La chiamata è asincrona su entrambe le piattaforme, ma la chiave cercata è diversa.

In AEM as a Cloud Service, la chiave è fissa, poiché ogni ambiente ha il proprio segreto dietro lo stesso nome chiave:

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

In Edge Delivery Services, compilare prima la chiave dal sito corrente, poiché un edgeFunctions.yaml condiviso dichiara una chiave separata per sito:

// 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 volta che disponi del token, utilizzalo nella richiesta in uscita nello stesso modo su entrambe le piattaforme:

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

Mantieni il segreto all’interno della funzione Edge di AEM. Non restituirlo al client né registrarlo.

Linee guida

Risorse aggiuntive