Créer un point d’entrée d’API avec les fonctions Edge

Une fonction AEM Edge est un module JavaScript qui s’exécute sur le réseau CDN Adobe (Fastly Compute). Vous l’exposez en tant que un ou plusieurs points d’entrée HTTP en associant les règles du sélecteur d’origine du réseau CDN à un gestionnaire d’événements de récupération dans votre code.

Cette page couvre le contrat et les fichiers clés. Vous pouvez écrire n’importe quelle logique dans le gestionnaire, y compris les appels de fetch() sortants vers d’autres systèmes. Gardez le gestionnaire rapide et de courte durée pour qu’il s’adapte au runtime Edge.

Prérequis

Pour la première configuration, voir Configuration sur AEM as a Cloud Service ou Configuration sur Edge Delivery Services.

Comment une requête HTTP atteint votre code

Une requête atteint votre fonction AEM Edge en deux étapes : le sélecteur d’origine du réseau CDN achemine le point d’entrée vers la fonction, puis votre gestionnaire d’événements de récupération s’exécute.

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

Le sélecteur d’origine et le nom de la fonction doivent être alignés. Si edgeFunctions.yaml déclare my-edge-function, le sélecteur d’origine utilise edgefunction-my-edge-function dans 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

Chaque point d’entrée a besoin de sa propre règle de sélecteur d’origine dans cdn.yaml. Une fonction AEM Edge peut servir plusieurs points d’entrée, mais le réseau CDN doit transférer chaque chemin d’accès à cette fonction. Définissez skipCache: false pour autoriser la mise en cache du réseau CDN pour les réponses stables ou skipCache: true pour contourner le cache du réseau CDN pour les réponses dynamiques ou personnalisées.

Pour les options du sélecteur d’origine, voir ​ Sélecteurs d’origine ​.

Gérer les requêtes

Chaque fonction AEM Edge enregistre un gestionnaire d’événements de récupération. Le réseau CDN d’Adobe appelle ce gestionnaire pour chaque requête correspondante. Le gestionnaire lit le Request entrant, exécute votre logique et renvoie un 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();
  }
}

Points clés :

La correspondance des points d’entrée existe dans index.js. Au fur et à mesure que vos points d’entrée se développent, déplacez la logique du gestionnaire dans des fichiers distincts et importez-les, comme my-api.js le fait dans l’exemple ci-dessus. Consultez Utilisation de plusieurs points d’entrée avec des fonctions Edge pour obtenir des modèles à mesure que votre surface API se développe.

Écrire la logique du gestionnaire

Dans chaque gestionnaire de point d’entrée, vous pouvez exécuter n’importe quel JavaScript adapté au runtime Edge. Gardez le travail rapide et de courte durée. Privilégiez les transformations légères, les recherches géographiques, les réponses JSON ou HTML simples et les petites agrégations aux calculs lourds ou de longue durée.

Une réponse minimale ressemble à ceci :

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

Vous pouvez renvoyer du texte brut, JSON ou HTML. Définissez des en-têtes sur la Response pour contrôler le type de contenu et la mise en cache :

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

Si vous avez besoin de données provenant d’un autre système, appelez-les avec fetch(). Conserver les informations d’identification dans la fonction AEM Edge. N’exposez pas de secrets dans le JavaScript client.

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

Les appels de fetch() sortants suivent généralement ce modèle :

Des limites de plateforme s’appliquent. Chaque appel prend en charge jusqu’à 32 appels de récupération sortante . Pour connaître le comportement du cache sur les appels de récupération, voir Mise en cache dans les fonctions AEM Edge.

Autres exemples de code

Pour obtenir des exemples de travail complets, consultez le guide des fonctions AEM Edge ​ :

Ressources supplémentaires