Usar configurações e segredos com as funções do Edge

Saiba como transmitir configurações e segredos não confidenciais para uma Função Edge do AEM por meio de edgeFunctions.yaml e como lê-los em seu código.

Configurações versus segredos

configs e secrets são pares de chave-valor expostos na função Edge do AEM.

A diferença é onde o valor está e quão sensível ele é.

Onde você declara configurações e segredos

Declarar ambos em data em edgeFunctions.yaml, como irmãos de functions. Eles não estão aninhados em uma função 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}}

Os nomes de chave fazem distinção entre maiúsculas e minúsculas. O key declarado aqui tem o mesmo nome que o código lê no tempo de execução.

Para todas as propriedades suportadas, consulte Declarar funções.

Usar configurações

As configurações mantêm valores não confidenciais que variam de acordo com o ambiente. Os valores de configuração são sempre cadeias de caracteres, portanto, converta-os quando precisar de um número ou booleano.

Ler configurações no código

Abra o repositório config_default e chame get() com a chave declarada. A chamada é síncrona.

// 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 segredos

Os segredos contêm valores confidenciais, como um token de API. O valor permanece em um segredo do Cloud Manager. Seu edgeFunctions.yaml faz referência a ele com a sintaxe ${{SECRET_NAME}}, de modo que o valor nunca aparece no Git.

Dois nomes estão envolvidos, e eles são diferentes de propósito.

Este exemplo usa uma chave e um segredo, o padrão para o AEM as a Cloud Service. No Edge Delivery Services, você repete o padrão uma vez por site, já que um pipeline de configuração serve todos os três sites.

Adicionar o segredo no AEM as a Cloud Service

Defina o segredo do Cloud Manager e execute o pipeline de configuração antes de usá-lo na função Edge do AEM. Cada ambiente (RDE, Dev, Stage, Prod) tem sua própria guia Configuração, portanto, um segredo que você adiciona ao Dev não existe no Stage ou no Prod até que você o adicione também.

Adicionar o segredo no Edge Delivery Services

O Edge Delivery Services tem um pipeline de configuração por programa, não um por site. Ele implanta um único edgeFunctions.yaml para todo o programa, compartilhado por cada site, em vez de um arquivo separado por site.

Os sites Desenvolvimento, Preparo e Produção compartilham esse pipeline, portanto, não é possível adicionar o mesmo nome de variável três vezes com três valores diferentes e você não pode depender de um edgeFunctions.yaml específico de ramificação para escolher o correto.

Prefixe cada nome de variável com seu site para que os três sites nunca colidam, por exemplo DEV_TRIPS_API_TOKEN, STAGE_TRIPS_API_TOKEN e MAIN_TRIPS_API_TOKEN. Declare todos os três no mesmo edgeFunctions.yaml e deixe seu código escolher o correto no tempo de execução.

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

A função Edge do AEM deve decidir qual chave ler no tempo de execução, com base no site que está sendo veiculado no momento. A próxima seção mostra a pesquisa.

Ler segredos no código

Leia o segredo no tempo de execução por meio do auxiliar SecretStoreManager fornecido pela placa-mãe em src/lib/config.js. Ele lê do armazenamento secret_default. A chamada é assíncrona em ambas as plataformas, mas a chave que você procura é diferente.

No AEM as a Cloud Service, a chave é fixa, já que cada ambiente tem seu próprio segredo atrás do mesmo nome de chave:

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

No Edge Delivery Services, compile a chave do site atual primeiro, já que um edgeFunctions.yaml compartilhado declara uma chave separada por site:

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

Depois de receber o token, use-o na solicitação de saída da mesma maneira em ambas as 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}` },
});

Mantenha o segredo dentro da Função Edge do AEM. Não retorne-o ao cliente nem registre-o.

Diretrizes

Recursos adicionais