Filtri di richiesta HTTP con funzioni Edge

IMPORTANT
AEM Edge Functions è attualmente in versione beta. Le funzioni e la documentazione potrebbero cambiare. Per ricevere commenti, contattare aemcs-edgecompute-feedback@adobe.com.

Scopri come implementare il filtro delle richieste HTTP con le funzioni Edge di AEM per riscrivere o reindirizzare le richieste o modificare le risposte HTTP.

Quando filtrare le richieste HTTP con le funzioni Edge

Una funzione Edge di AEM può fungere da proxy inverso che esegue l’elaborazione avanzata della richiesta e della risposta prima che raggiungano l’origine o il client.

I due scenari sono:

Regola la richiesta prima che raggiunga l’origine

Intercetta il traffico sulla strada per l’origine a:

  • Riscrivere l’origine, il percorso o la query della richiesta. Indirizza la richiesta a un backend, percorso o stringa di query diverso in modo che l’origine riceva la risorsa corretta.
  • Riscrivi intestazioni richiesta. Aggiungere, rimuovere o modificare le intestazioni prima che la richiesta raggiunga l’origine. Ad esempio, puoi aggiungere un’intestazione geografica o di accesso prevista dall’origine, rimuovere le intestazioni ignorate dall’origine o modificare il valore di un’intestazione per modificare il comportamento della richiesta.

Modifica la risposta prima che raggiunga il client

Intercetta il traffico tornando al client (visitatore) per:

  • Modifica la risposta HTML. Inserisci JavaScript, contenuti personalizzati, riscrivi collegamenti o unisci in un’intestazione e un piè di pagina prima che la pagina raggiunga il browser.
  • Reindirizzamento al perimetro. Distribuisci un ampio set di reindirizzamenti URL da legacy a new dalla rete CDN, in particolare quando le regole di reindirizzamento richiedono una logica programmatica.
  • Personalizza in base al contesto della richiesta. Modifica una pagina o una sezione di una pagina in base alla geolocalizzazione, al dispositivo o al pubblico per i visitatori pubblici. Questo vale per il traffico di pubblicazione sul dominio del sito e non per il traffico di authoring.

Implementare il filtro delle richieste HTTP

Il filtro delle richieste HTTP utilizza due file. Il file config/cdn.yaml determina il traffico da intercettare e indirizzare alla funzione Edge di AEM. Il file src/index.js esegue l’adeguamento della richiesta o della risposta.

Il selettore di origine e il nome della funzione devono essere allineati. Se edgeFunctions.yaml dichiara my-edge-function, il selettore di origine utilizza edgefunction-my-edge-function in cdn.yaml.

Configurare il filtro CDN

# config/cdn.yaml (origin selector excerpt)
kind: "CDN"
version: "1"
data:
  originSelectors:
    rules:
      - name: route-to-edge-function
        when:
          allOf:
            - { reqProperty: tier, equals: "publish" } # publish traffic only; skip author
            - { reqProperty: domain, equals: "www.example.com" } # your site hostname
            - { reqProperty: originalPath, matches: "(/[^./]+|\\.html|/)$" } # page URLs; skip static assets (.css, .js, images, fonts)
            # - { reqProperty: method, in: ["GET", "HEAD"] } # optional: navigation only; skip POST, PUT, and other methods with bodies
            - { reqHeader: x-edgefunction-request, exists: false } # skip loopback requests to prevent infinite loops
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>

Se una delle condizioni non riesce, la richiesta non raggiunge mai la funzione Edge di AEM. Inizia con il minor numero di condizioni necessarie alla funzione e aggiungi altro solo per rendere più preciso l’indirizzamento. Per tutte le proprietà e gli operatori supportati, vedi Selettori di origine.

Implementare il gestore

Ogni funzione Edge di AEM registra un gestore di eventi di recupero. Utilizza il gestore per regolare la richiesta prima che raggiunga l’origine, modificare la risposta prima che raggiunga il client o entrambi.

Il seguente frammento di codice illustra il filtro delle richieste e la modifica delle risposte in una funzione Edge di AEM.

// src/index.js
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  const req = event.request;
  const url = new URL(req.url);

  try {
    // ------------------------------------------------------------
    // --- Request filtering: adjust before origin ---
    // ------------------------------------------------------------

    // Example: Rewrite origin, path, or query
    // Replace origin based on some criteria such as path or query
    const newOriginRequest = new Request(`https://origin.example.com${url.pathname}${url.search}`);
    const newOriginResponse = await fetch(newOriginRequest);
    // Return the new origin response
    return newOriginResponse;

    ...

    // Example: Rewrite request headers before reaching the origin
    // Add or modify headers before the request reaches the origin, like adding an authorization token based on exchange with an external service.
    const originRequest = new Request(req, {
      headers: new Headers({ ...Object.fromEntries(req.headers), "Authorization": "Bearer <token>" }),
    });
    const originResponse = await fetch(originRequest);
    return originResponse;

    ...

    // ------------------------------------------------------------
    // --- Response filtering: modify before client ---
    // ------------------------------------------------------------

    // Example: Change response HTML (fetch from origin, transform the body)
    // Fetch the response from the origin, transform the body, and return the transformed response.
    const originRequest = new Request(`https://origin.example.com${url.pathname}`);
    const originResponse = await fetch(originRequest);
    const transformedHtml = transformHtml(await originResponse.text());
    return new Response(transformedHtml, { status: 200, headers: originResponse.headers });

    ...

    // Example: Redirect at the edge
    // Redirect the client to a new path, like a legacy URL to a new URL.
    return Response.redirect("https://www.example.com/new-path", 301);

    ...

    // Example: Personalize by request context (geo, device, or audience)
    // Fetch the response from the origin, personalize the body, and return the personalized response.
    const originRequest = new Request(`https://origin.example.com${url.pathname}`);
    const originResponse = await fetch(originRequest);
    const personalizedHtml = personalizeHtml(await originResponse.text());
    return new Response(personalizedHtml, { status: 200, headers: originResponse.headers });

    return new Response("Not implemented", { status: 501 });
  } catch (err) {
    console.log(err);
    return new Response("Error", { status: 500 });
  }
}

Punti chiave:

Concetto
Dettagli
Filtro CDN
when + allOf in cdn.yaml instrada solo il traffico corrispondente alla funzione Edge di AEM
Filtro richieste
Crea un nuovo Request con un’origine, un percorso, una query o intestazioni diverse prima di fetch() all’origine
Filtro risposte
Restituisce un nuovo Response con HTML trasformato, un reindirizzamento o un contenuto personalizzato
Looopback CDN
Imposta un’intestazione sentinella sulle chiamate interne fetch() in modo che la rete CDN instradi il traffico di loopback all’origine

Linee guida per la progettazione

  • Mantenere i filtri più stretti possibile.
  • Limita le funzioni di navigazione a GET e HEAD.
  • Evita cicli infiniti nel loopback CDN impostando un’intestazione sentinella nelle chiamate interne di fetch().
  • Distribuisci cdn.yaml aggiornato tramite la pipeline di configurazione di Cloud Manager.

Impedisci cicli infiniti nel loopback CDN

Un ciclo infinito può verificarsi quando una funzione Edge di AEM recupera il contenuto dall’origine tramite la rete CDN. Il recupero torna alla rete CDN, corrisponde alla stessa regola del selettore di origine e viene indirizzato nuovamente alla funzione.

Per evitare questo problema, è possibile escludere le richieste di loopback dalla regola del selettore di origine impostando un’intestazione sentinella (ad esempio, x-edgefunction-request). La richiesta iniziale del visitatore non ha un’intestazione e raggiunge la funzione Edge di AEM. La richiesta di loopback porta l’intestazione, genera un errore nella condizione e instrada all’origine.

I seguenti snippet di codice e configurazione mostrano come evitare loop infiniti sul loopback CDN.

// src/index.js
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
...

// In the handler: set the sentinel on the loopback fetch
const loopbackRequest = new Request(`https://www.example.com${url.pathname}`, {
  headers: { "x-edgefunction-request": "true" },
});
await fetch(loopbackRequest);

Consulta Esempi di funzioni Edge di AEM per informazioni su come impostare l’intestazione sentinella nel gestore di funzioni Edge di AEM.

# config/cdn.yaml (origin selector excerpt)
kind: "CDN"
version: "1"
data:
  originSelectors:
    rules:
      - name: route-to-edge-function
        when:
          allOf:
            ...
            - { reqHeader: x-edgefunction-request, exists: false } # skip loopback requests to prevent infinite loops
            ...

Consulta Esempi di funzioni Edge di AEM per informazioni su come escludere le richieste che già contengono l’intestazione sentinella nella configurazione CDN.

Esempi completi

L’archivio AEM Edge Functions examples include funzioni intercettore con config/cdn.yaml regole complete:

Esempio
Archivio
Cosa dimostra
Trasformatore AEM as a Cloud Service HTML
publish-delivery-transformer
Filtro di pubblicazione pagina per siti AEM as a Cloud Service che inseriscono uno snippet di JavaScript nella risposta di HTML e impediscono il loopback CDN
Trasformatore Edge Delivery HTML
edge-delivery-transformer
Filtro di pubblicazione pagina per siti Edge Delivery Services che inseriscono intestazione e piè di pagina del sito nella risposta di HTML
Ricerca mappa di reindirizzamento
publish-delivery-redirect-map
Filtro di pagina GET/HEAD che reindirizza a un URL legacy e impedisce il loopback CDN

Risorse aggiuntive

recommendation-more-help
experience-manager-learn-help-cloud-service