Funções do AEM Edge aem-edge-functions

O AEM Edge Functions permite executar o JavaScript na camada de CDN, aproximando o processamento de dados do usuário final. Isso reduz a latência e permite experiências responsivas e dinâmicas sem uma viagem de ida e volta à sua origem.

Casos de uso comuns incluem:

O AEM Edge Functions é compatível com o Edge Delivery Services e o AEM as a Cloud Service Java-stack, para clientes do AEM Sites.

Siga este tutorial para obter uma apresentação concreta das variações de pilha de Java do Edge Delivery Services e do AEM as a Cloud Service.

Principais benefícios key-benefits

Pré-requisitos prerequisites

Configurar setup

Instalar a CLI do Adobe install-adobe-cli

Instale a CLI do Adobe Developer (aio):

npm install -g @adobe/aio-cli

Instale o plug-in AEM Edge Functions:

aio plugins install @adobe/aio-cli-plugin-aem-edge-functions

Autentique e configure o plug-in para o seu ambiente:

aio login
aio aem edge-functions setup

O comando de configuração solicita que você faça logon e selecione o ambiente do AEM no qual deseja usar as funções do AEM Edge.

Clonar a chapa boilerplate

Copie o aem-edge-functions-boilerplate no seu próprio repositório e instale as dependências:

npm install

Registrar sua função do AEM Edge register-your-function

As Funções do AEM Edge são declaradas em um arquivo de configuração YAML e implantadas por meio do pipeline de configuração do Cloud Manager.

​1. Definir um pipeline de configuração configuration-pipeline

Antes de criar uma função de borda, verifique se no Cloud Manager existe um pipeline de configuração para o seu ambiente (se estiver usando a pilha de Java da AEM) ou um pipeline da Edge Delivery Services se o seu projeto estiver implementado com o Edge Delivery Services. Consulte Usar Pipelines de Configuração para obter informações sobre como configurar os pipelines.

​2. Declare sua função do Edge declare-functions

Crie um arquivo chamado edgeFunctions.yaml no diretório de configuração:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
    # add advanced configuration under here

Os ambientes Java-stack têm uma função de borda e as implementações do Edge Delivery Services têm três funções de borda. As teclas opcionais de nível superior são:

Consulte a configuração avançada, como configs, secrets e kvs, na seção de configuração avançada abaixo.

​3. Implantar a função do Edge por meio do Cloud Manager deploy-functions-via-cm

Usando o Cloud Manager, implante o pipeline para que a função de borda seja registrada na CDN.

Criar, criar e implantar o código de função do AEM Edge build-deploy

Autor author

Escreva a lógica comercial do código de função de borda, usando a pasta src da chapa como ponto de partida.

Build build

Crie um pacote do código de função de borda para implantação:

aio aem edge-functions build

Implantar deploy

Implante o código da função de borda empacotada na função de borda nomeada. O argumento function-name deve corresponder ao valor name em edgeFunctions.yaml:

aio aem edge-functions deploy <function-name>

Teste test

Verifique se a função de borda funciona conforme esperado. Você pode testá-la em:

edgefunction-pXXXXX-eYYYYY-<function name>.adobeaemcloud.com/<path>

Por exemplo, para a pilha de Java do AEM:

edgefunction-pXXXXX-eYYYYY-my-edge-function.adobeaemcloud.com/weather

ou para Edge Delivery Services:

edgefunction-pXXXXX-dYYYYY-my-edge-function.adobeaemcloud.com/weather

Este domínio com o prefixo edgefunction é apenas para depuração, mas não deve ser referenciado para tráfego ao vivo, pois não há garantia de que seja um nome estável. Para determinar o valor de dAAAA, consulte a saída do comando deploy.

Conectar ao fluxo de entrega de conteúdo wiring

O tráfego de função do Edge deve ser enviado para o domínio do site, que normalmente é um domínio personalizado para AEM Java-stack, e deve ser um domínio personalizado para Edge Delivery Services Sites.

​1. Definir seletores de origem origin-selectors

As funções do Edge são invocadas pelo roteamento de tráfego CDN para elas por meio de regras do seletor de origem. Adicione o seguinte ao arquivo de configuração cdn.yaml (ou crie um caso ele não exista):

kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-weather-to-edge-function
        when: { reqProperty: path, equals: "/weather" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function
      - name: route-hello-world-to-edge-function
        when: { reqProperty: path, equals: "/hello-world" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function

As regras do seletor de origem permitem rotear o tráfego para suas funções de borda com base em qualquer condição disponível no mecanismo de regras CDN, como um caminho, domínio ou cabeçalho de solicitação específico. Várias regras podem rotear caminhos diferentes para a mesma função de borda. Consulte Seletores de Origem para obter a sintaxe de regra completa.

​2. Implantar a configuração deploy-to-cdn

Confirme cdn.yaml no repositório Git do Cloud Manager e acione o pipeline de configuração. Depois que o pipeline for concluído com êxito, seus pontos de extremidade de função de borda estarão disponíveis em:

Para depuração, você pode referenciar a função de borda no domínio publish-pXXXXX-eYYYYY.adobeaemcloud.com (para a pilha de Java do AEM) ou publish-pXXXXX-dYYYYY.adobeaemcloud.com (para sites do Edge Delivery Services). Não use esse domínio para uso de produção, pois não há garantia de que seja um nome estável. Para determinar o valor de dAAAA, consulte a saída do comando deploy.

Desenvolvimento local local-development

Executar localmente local-run

Iniciar um servidor de desenvolvimento local em http://127.0.0.1:7676:

aio aem edge-functions serve

Consulte esta documentação do Compute JavaScript para obter detalhes sobre o que o tempo de execução local suporta.

Teste test-localdev

Execute o conjunto de testes com Mocha:

npm run test

Depuração remota remote-debugging

O Adobe Managed CDN não expõe um depurador remoto, mas expõe o fluxo de log. Siga os logs de uma função implantada para receber saída de console.log diretamente em seu terminal:

aio aem edge-functions tail-logs <function-name>

Armazenamento em cache e limpeza de cache caching

As funções do Edge podem reduzir significativamente a carga de origem e melhorar os tempos de resposta, armazenando dados em cache na borda. No entanto, o armazenamento em cache requer um design intencional, principalmente em Funções Edge, nas quais duas camadas de cache independentes estão envolvidas:

Browser → AEM CDN (CDN Cache) → AEM Edge Functions (Fetch Cache) → Backend (AEM, APIs, etc.)

Antes de configurar o armazenamento em cache, considere como seu conteúdo se comporta:

Como a CDN e o cache de busca interno da Função Edge operam independentemente, uma alteração nos dados subjacentes requer a invalidação deliberada de ambas camadas. A compreensão dessa arquitetura é essencial para o gerenciamento confiável de cache.

Para obter orientação técnica detalhada sobre como configurar o comportamento de cache, controlar a duração do cache, usar chaves substitutas e limpar o conteúdo em cache, consulte Armazenamento em cache nas funções do AEM Edge.

Limitações limitations

Máximo de Chamadas Fetch de Saída por Chamada max-fetch-calls

As Funções do AEM Edge impõem um limite rígido de 32 solicitações de back-end por execução (ou seja, por solicitação de entrada manipulada pela sua função). Quando esse limite for atingido, qualquer outra chamada fetch() falhará com o seguinte erro:

Requested backend named '…' does not exist

Quando você vê esse erro e sua configuração de origem está correta, a causa mais provável é que a cota de solicitação de back-end por invocação tenha sido esgotada. Consulte Limites de recursos do Fastly Compute para obter a lista completa de limites de plataforma.

Configuração de função avançada do Edge advanced-function-configuration

Origens origins

Por padrão, as funções de borda podem buscar de qualquer origem. Para restringir uma função a um conjunto definido de origens, declare-as em origins em edgeFunctions.yaml:

origins:
  - name: my-origin-name
    domain: example.com

Referencie a origem nomeada em seu código de função usando a opção de busca backend:

const request = new Request("https://example.com/test");
const response = await fetch(request, { backend: "my-origin-name" });

Variáveis de configuração da função do Edge function-configuration

Exponha variáveis de ambiente a suas funções usando a chave configs em edgeFunctions.yaml. Os valores são armazenados em um repositório de configuração chamado config_default:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: LOG_LEVEL
      value: DEBUG

Leia os valores de configuração no seu código de função:

import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore('config_default');
const logLevel = config.get('LOG_LEVEL') || 'info';

Variáveis Secretas de Função do Edge function-secrets

Segredos são referenciados, não armazenados, em edgeFunctions.yaml. O campo value deve apontar para um segredo Cloud Manager usando a sintaxe ${{SECRET_REFERENCE}}. Primeiro defina o segredo subjacente no Cloud Manager — consulte Variáveis Secretas do Cloud Manager.

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  secrets:
    - key: API_TOKEN
      value: ${{API_TOKEN_SECRET}}

Recupere segredos em seu código de função usando o auxiliar SecretStoreManager da chapa padrão:

import { SecretStoreManager } from "./lib/config";

const apiToken = await SecretStoreManager.getSecret('API_TOKEN');

Armazenamento KV da função Edge function-kv-store

As funções do Edge podem ler e gravar dados arbitrários de valores-chave no tempo de execução por meio de um armazenamento KV. Para habilitá-lo, defina kvs: true em edgeFunctions.yaml:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  kvs: true

Isso provisiona um armazenamento KV vazio chamado kv_default. Preencha-o no tempo de execução a partir do código da função de borda usando a API de armazenamento KV Fastly:

import { KVStore } from "fastly:kv-store";

const kv = new KVStore('kv_default');

// Read a value
const entry = await kv.get('visit-count');
const count = entry ? Number(await entry.text()) : 0;

// Write a value
await kv.put('visit-count', String(count + 1));

Logs logging

O AEM Edge Functions é integrado ao recurso Encaminhamento de logs do AEM. Crie um arquivo logForwarding.yaml junto com seu edgeFunctions.yaml:

kind: "LogForwarding"
version: "1"
metadata:
  envTypes: ["rde", "dev", "stage", "prod"]
data:
  splunk:
    default:
      enabled: true
      host: "splunk-host.example.com"
      token: "${{SPLUNK_TOKEN}}"
      index: "AEMaaCS"

Use o agente de log no código da função para gravar entradas de log estruturadas:

import { Logger } from "fastly:logger";

const logger = new Logger("customerSplunk");
logger.log(JSON.stringify({
  method: event.request.method,
  url: event.request.url
}));