Criar um endpoint de API com funções do Edge

Uma função do AEM Edge é um módulo do JavaScript executado no Adobe CDN (Fastly Compute). Você o expõe como um ou mais pontos de extremidade HTTP emparelhando as regras do seletor de origem CDN com um manipulador de eventos de busca em seu código.

Esta página aborda o contrato e os arquivos principais. Você pode gravar qualquer lógica no manipulador, incluindo chamadas de saída do fetch() para outros sistemas. Mantenha o manipulador rápido e de curta duração para que ele se ajuste ao tempo de execução da borda.

Pré-requisitos

Para configuração pela primeira vez, consulte Configurar no AEM as a Cloud Service ou Configurar no Edge Delivery Services.

Como uma solicitação HTTP atinge seu código

Uma solicitação atinge a função Edge do AEM em duas etapas: o seletor de origem CDN roteia o ponto de extremidade para a função e, em seguida, o manipulador de eventos de busca é executado.

Browser → CDN origin selector (cdn.yaml) → AEM Edge Function (index.js) → Your handler logic (optional fetch to other systems)

O seletor de origem e o nome da função devem ser alinhados. Se edgeFunctions.yaml declara my-edge-function, o seletor de origem usa edgefunction-my-edge-function em cdn.yaml.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function #<name-of-the-function>

# config/cdn.yaml (origin selector excerpt)
kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-status-endpoint-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/status" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: false # false to use the CDN cache for this path
      - name: route-my-api-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/my-api" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: true # true to bypass the CDN cache for this path

Cada ponto de extremidade precisa de sua própria regra de seletor de origem em cdn.yaml. Uma função Edge do AEM pode atender a vários endpoints, mas o CDN deve encaminhar cada caminho para essa função. Defina skipCache: false para permitir o armazenamento em cache do CDN para respostas estáveis, ou skipCache: true para ignorar o cache do CDN para respostas dinâmicas ou personalizadas.

Para opções do seletor de origem, consulte Seletores de origem.

Manipular solicitações

Cada função do AEM Edge registra um manipulador de eventos de busca. O Adobe CDN chama esse manipulador para cada solicitação correspondente. O manipulador lê o Request recebido, executa sua lógica e retorna um Response.

// src/index.js
import { myApiHandler } from "./my-api.js";
import * as response from "./lib/response.js";

// entry point for the AEM Edge Function
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  // event.request is a standard Fetch API Request (method, URL, headers, body)
  const req = event.request;
  const url = new URL(req.url);

  try {
    // endpoint matching
    if (url.pathname === "/status" && req.method === "GET") {
      return new Response("OK", { status: 200 });
    } else if (url.pathname === "/my-api" && req.method === "GET") {
      return await myApiHandler(req, event.client);
    }
    // add more endpoints here

    return response.notFound();
  } catch (err) {
    console.log(err);
    return response.error();
  }
}

Pontos principais:

O ponto de extremidade correspondente vive em index.js. Conforme seus pontos de extremidade crescem, mova a lógica do manipulador para arquivos separados e importe-os, como my-api.js faz no exemplo acima. Consulte Atender vários pontos de extremidade com funções do Edge para ver os padrões à medida que a superfície da API se expande.

Escreva a lógica do manipulador

Dentro de cada manipulador de endpoint, é possível executar qualquer JavaScript que se ajuste ao tempo de execução da borda. Mantenha o trabalho rápido e de curta duração. Prefira transformações leves, pesquisas geográficas, respostas simples de JSON ou HTML e pequenas agregações a computação pesada ou de longa duração.

Uma resposta mínima tem esta aparência:

if (url.pathname === "/status" && req.method === "GET") {
  return new Response("OK", { status: 200 });
}

Você pode retornar JSON, HTML ou texto sem formatação. Defina cabeçalhos no Response para controlar o tipo de conteúdo e o cache:

return new Response(JSON.stringify({ status: "ok" }), {
  status: 200,
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "public, max-age=300",
  },
});

Quando precisar de dados de outro sistema, chame-o com fetch(). Mantenha as credenciais na Função Edge do AEM. Não exponha segredos no JavaScript do cliente.

// src/my-api.js
async function myApiHandler(req, client) {
  const backendRequest = new Request("https://api.example.com/data");

  // optionally, you can add headers to the request
  // backendRequest.headers.set("Authorization", `Bearer <your-access-token>`);

  const backendResponse = await fetch(backendRequest);

  if (!backendResponse.ok) {
    return new Response("Backend error", { status: 502 });
  }

  const data = await backendResponse.json();

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "max-age=300",
    },
  });
}

export { myApiHandler };

As chamadas de saída fetch() normalmente seguem este padrão:

Limites de plataforma se aplicam. Cada invocação dá suporte a até 32 chamadas de busca de saída. Para comportamento de cache em chamadas de busca, consulte Armazenamento em cache em funções do AEM Edge.

Mais exemplos de código

Para obter exemplos completos de trabalho, consulte a descrição das Funções do AEM Edge:

Recursos adicionais