Introduzione

Il traffico passa attraverso la rete CDN a un livello di server web Apache, che supporta moduli tra cui Dispatcher. Per migliorare le prestazioni, Dispatcher viene utilizzato principalmente come cache per limitare l’elaborazione sui nodi di pubblicazione.
È possibile applicare delle regole alla configurazione di Dispatcher per modificare eventuali impostazioni di scadenza predefinite della cache, con conseguente memorizzazione nella cache della rete CDN. Dispatcher rispetta anche le intestazioni di scadenza della cache risultanti se enableTTL è abilitato nella configurazione di Dispatcher, il che significa che aggiornerà contenuti specifici anche al di fuori di quelli ripubblicati.

Questa pagina descrive anche come viene invalidata la cache di Dispatcher e come funziona il caching a livello di browser per quanto riguarda le librerie lato client.

Memorizzazione in cache

HTML/Text

• per impostazione predefinita, viene memorizzato nella cache dal browser per cinque minuti, in base al cache-control intestazione emessa dal livello Apache. Anche la rete CDN rispetta questo valore.
• l’impostazione predefinita di HTML/Text caching può essere disabilitata definendo DISABLE_DEFAULT_CACHING variabile in global.vars:

Define DISABLE_DEFAULT_CACHING

Ciò può essere utile, ad esempio, quando la logica di business richiede la regolazione fine dell’intestazione age (con un valore basato sul giorno del calendario) poiché per impostazione predefinita l’intestazione age è impostata su 0. Detto questo, fai attenzione quando disattivi la memorizzazione in cache predefinita.

• può essere ignorato per tutto il contenuto HTML/Text definendo EXPIRATION_TIME variabile in global.vars utilizzando gli strumenti di Dispatcher SDK as a Cloud Service dell’AEM.

• può essere ignorato a un livello più granulare, incluso il controllo indipendente della CDN e della cache del browser, con il seguente Apache mod_headers direttive:

  <LocationMatch "^/content/.*\.(html)$">
       Header set Cache-Control "max-age=200"
       Header set Surrogate-Control "max-age=3600"
       Header set Age 0
  </LocationMatch>
  

  NOTA

  L’intestazione Surrogate-Control si applica alla rete CDN gestita dall’Adobe. Se si utilizza un CDN gestita dal cliente, potrebbe essere necessaria un’intestazione diversa a seconda del provider CDN.

  Presta attenzione quando imposti intestazioni di controllo cache globale o corrispondenti a un’ampia regola, in modo che non vengano applicate a contenuti che devono essere mantenuti privati. Valuta l’utilizzo di più direttive per garantire che le regole vengano applicate in modo granulare. Detto questo, AEM as a Cloud Service rimuoverà l’intestazione della cache se rileva che è stata applicata a ciò che rileva come non memorizzabile in cache da Dispatcher, come descritto nella documentazione di Dispatcher. Per obbligare l’AEM ad applicare sempre le intestazioni di caching, è possibile aggiungere sempre opzione come segue:

  <LocationMatch "^/content/.*\.(html)$">
       Header unset Cache-Control
       Header unset Expires
       Header always set Cache-Control "max-age=200"
       Header set Age 0
  </LocationMatch>
  

  È necessario assicurarsi che un file in src/conf.dispatcher.d/cache ha la seguente regola (nella configurazione predefinita):

  /0000
  { /glob "*" /type "allow" }
  

• Per evitare che un contenuto specifico venga memorizzato nella cache alla rete CDN, imposta l’intestazione Cache-Control su privato. Ad esempio, quanto segue impedisce il contenuto HTML in una directory denominata protetto dalla memorizzazione nella cache nella rete CDN:

     <LocationMatch "/content/secure/.*\.(html)$">.  // replace with the right regex
     Header unset Cache-Control
     Header unset Expires
     Header always set Cache-Control "private"
    </LocationMatch>
  

• Anche se il contenuto HTML impostato su privato non verrà memorizzato nella cache della rete CDN, può essere memorizzato nella cache del dispatcher se Memorizzazione in cache sensibile alle autorizzazioni è configurato, in modo che solo gli utenti autorizzati possano ricevere il contenuto.

  NOTA

  Gli altri metodi, tra cui progetto dispatcher-ttl AEM ACS Commons, non eseguirà correttamente l'override dei valori.

  NOTA

  Tieni presente che Dispatcher potrebbe comunque memorizzare in cache il contenuto in base al proprio regole di caching. Per rendere il contenuto veramente privato, assicurati che non venga memorizzato in cache da Dispatcher.

Librerie lato client (js,css)

• Quando si utilizza il framework libreria AEM lato client, il codice JavaScript e CSS viene generato in modo tale che i browser possano memorizzarlo nella cache indefinitamente, poiché eventuali modifiche si manifestano come nuovi file con un percorso univoco. In altre parole, HTML che fa riferimento alle librerie client verrà prodotto in base alle esigenze, affinché i clienti possano visualizzare nuovi contenuti non appena vengono pubblicati. Il controllo cache è impostato su "immutabile" o 30 giorni per i browser più vecchi che non rispettano il valore "immutabile".
• vedi la sezione Librerie lato client e coerenza delle versioni per ulteriori dettagli.

Immagini e qualsiasi contenuto di dimensioni sufficienti per essere archiviato nell'archivio BLOB

Il comportamento predefinito per i programmi creati dopo metà maggio 2022 (in particolare, per gli ID programma superiori a 65000) consiste nella memorizzazione in cache per impostazione predefinita, nel rispetto anche del contesto di autenticazione della richiesta. I programmi meno recenti (ID di programma uguali o inferiori a 65000) non memorizzano in cache il contenuto BLOB per impostazione predefinita.

In entrambi i casi, le intestazioni di memorizzazione in cache possono essere ignorate su un livello a grana più fine a livello di Apache/Dispatcher utilizzando Apache mod_headers direttive, ad esempio:

   <LocationMatch "^/content/.*\.(jpeg|jpg)$">
     Header set Cache-Control "max-age=222"
     Header set Age 0
   </LocationMatch>

Quando modifichi le intestazioni di memorizzazione in cache a livello di Dispatcher, fai attenzione a non creare una cache troppo ampia; consulta la discussione nella sezione HTML/testo. sopra. Inoltre, assicurati che le risorse destinate a essere mantenute private (anziché memorizzate in cache) non facciano parte del LocationMatch filtri direttiva.

Nuovo comportamento di caching predefinito

Il livello AEM imposterà le intestazioni cache a seconda che l’intestazione cache sia già stata impostata e il valore del tipo di richiesta. Tieni presente che se non è stata impostata alcuna intestazione di controllo cache, il contenuto pubblico viene memorizzato in cache e il traffico autenticato viene impostato su privato. Se è stata impostata un’intestazione di controllo cache, le intestazioni della cache non verranno toccate.

Sebbene non sia consigliato, è possibile modificare il nuovo comportamento predefinito in modo che segua il comportamento precedente (ID programma uguali o inferiori a 65000) impostando la variabile di ambiente Cloud Manager AEM_BLOB_ENABLE_CACHING_HEADERS su false.

Comportamento di memorizzazione nella cache predefinito precedente

Per impostazione predefinita, il livello AEM non memorizza in cache il contenuto BLOB.

Al momento, le immagini nell’archiviazione BLOB contrassegnate come private non possono essere memorizzate nella cache in Dispatcher utilizzando Memorizzazione in cache sensibile alle autorizzazioni. L’immagine viene sempre richiesta all’origine dell’AEM e trasmessa se l’utente è autorizzato.

Altri tipi di file di contenuto nell’archivio nodi

• nessuna memorizzazione predefinita nella cache
• impossibile impostare il valore predefinito con EXPIRATION_TIME variabile utilizzata per i tipi di file html/testo
• La scadenza della cache può essere impostata con la stessa strategia LocationMatch descritta nella sezione html/text specificando il valore regex appropriato

Ulteriori ottimizzazioni

• Evita di utilizzare User-Agent nell'ambito del Vary intestazione. Le versioni precedenti della configurazione predefinita di Dispatcher (precedenti alla versione 28 di Archetipo) includevano questo elemento e si consiglia di rimuoverlo seguendo la procedura riportata di seguito.

  • Individuare i file vhost in <Project Root>/dispatcher/src/conf.d/available_vhosts/*.vhost
  • Rimuovi o commenta la riga: Header append Vary User-Agent env=!dont-vary da tutti i file vhost, ad eccezione di default.vhost, che è di sola lettura

• Utilizza il Surrogate-Control intestazione per controllare la memorizzazione nella cache CDN indipendentemente dalla memorizzazione nella cache del browser

• Valuta l’applicazione stale-while-revalidate e stale-if-error direttive per consentire l’aggiornamento in background ed evitare mancati riscontri nella cache, mantenendo i contenuti veloci e aggiornati per gli utenti.

  • Esistono molti modi per applicare queste direttive, ma con l'aggiunta di un tempo di 30 minuti stale-while-revalidate a tutte le intestazioni di controllo cache è un buon punto di partenza.

• Seguono alcuni esempi per vari tipi di contenuto, che possono essere utilizzati come guida durante la configurazione di regole di caching personalizzate. Valuta e verifica attentamente la configurazione e i requisiti specifici:

  • Memorizza nella cache le risorse della libreria client mutabili per 12h e aggiorna in background dopo 12h.

    <LocationMatch "^/etc\.clientlibs/.*\.(?i:json|png|gif|webp|jpe?g|svg)$">
       Header set Cache-Control "max-age=43200,stale-while-revalidate=43200,stale-if-error=43200,public" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

  • Memorizza nella cache le risorse della libreria client immutabili a lungo termine (30 giorni) con aggiornamento in background per evitare errori irreversibili.

    <LocationMatch "^/etc\.clientlibs/.*\.(?i:js|css|ttf|woff2)$">
       Header set Cache-Control "max-age=2592000,stale-while-revalidate=43200,stale-if-error=43200,public,immutable" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

  • Memorizza nella cache le pagine HTML per 5 minuti con aggiornamento in background 1 ora nel browser e 12 ore nella rete CDN. Le intestazioni Cache-Control verranno sempre aggiunte, pertanto è importante assicurarsi che le pagine HTML corrispondenti in /content/* siano destinate a essere pubbliche. In caso contrario, considera l’utilizzo di un’espressione regex più specifica.

    <LocationMatch "^/content/.*\.html$">
       Header unset Cache-Control
       Header always set Cache-Control "max-age=300,stale-while-revalidate=3600" "expr=%{REQUEST_STATUS} < 400"
       Header always set Surrogate-Control "stale-while-revalidate=43200,stale-if-error=43200" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

  • Cache content services/Sling model exporter JSON response per 5 minuti con aggiornamento in background 1 ora sul browser e 12 ore sulla CDN.

    <LocationMatch "^/content/.*\.model\.json$">
       Header set Cache-Control "max-age=300,stale-while-revalidate=3600" "expr=%{REQUEST_STATUS} < 400"
       Header set Surrogate-Control "stale-while-revalidate=43200,stale-if-error=43200" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

  • Memorizza nella cache gli URL immutabili del componente immagine principale a lungo termine (30 giorni) con aggiornamento in background per evitare errori irreversibili.

    <LocationMatch "^/content/.*\.coreimg.*\.(?i:jpe?g|png|gif|svg)$">
       Header set Cache-Control "max-age=2592000,stale-while-revalidate=43200,stale-if-error=43200,public,immutable" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

  • Memorizza nella cache le risorse mutabili da DAM come immagini e video per 24 ore e aggiornamento in background dopo 12 ore per evitare errori irreversibili

    <LocationMatch "^/content/dam/.*\.(?i:jpe?g|gif|js|mov|mp4|png|svg|txt|zip|ico|webp|pdf)$">
       Header set Cache-Control "max-age=43200,stale-while-revalidate=43200,stale-if-error=43200" "expr=%{REQUEST_STATUS} < 400"
       Header set Age 0
    </LocationMatch>
    

Comportamento richiesta HEAD

Quando viene ricevuta una richiesta HEAD al CDN di Adobe per una risorsa che è non memorizzata nella cache, la richiesta viene trasformata e ricevuta dall’istanza di Dispatcher e/o AEM come richiesta di GET. Se la risposta è memorizzabile in cache, le richieste HEAD successive verranno servite dalla rete CDN. Se la risposta non è memorizzabile in cache, le richieste HEAD successive verranno passate all’istanza di Dispatcher e/o AEM per un periodo di tempo che dipende da Cache-Control TTL.

Parametri della campagna di marketing

Gli URL del sito web includono spesso parametri della campagna di marketing utilizzati per monitorare il successo di una campagna. Per utilizzare la cache del dispatcher in modo efficace, si consiglia di configurare i ignoreUrlParams proprietà come documentato qui.

Il ignoreUrlParams deve riportare un commento e deve fare riferimento al file conf.dispatcher.d/cache/marketing_query_parameters.any. Puoi modificare il file rimuovendo il commento dalle righe corrispondenti ai parametri rilevanti per i canali di marketing. Puoi aggiungere anche altri parametri.

/ignoreUrlParams {
{{ /0001 { /glob "*" /type "deny" }}}
{{ $include "../cache/marketing_query_parameters.any"}}
}

Annullamento della validità della cache di Dispatcher

In generale, non sarà necessario invalidare la cache di Dispatcher. Al contrario, quando il contenuto viene ripubblicato e la rete CDN rispetta le intestazioni di scadenza della cache, devi fare affidamento sull’aggiornamento della cache da parte di Dispatcher.

Annullamento della validità della cache del Dispatcher durante l’attivazione/disattivazione

Come per le versioni precedenti dell’AEM, la pubblicazione o l’annullamento della pubblicazione di pagine cancella il contenuto dalla cache di Dispatcher. Se si sospetta un problema di caching, è necessario ripubblicare le pagine in questione e assicurarsi che sia disponibile un host virtuale che corrisponda al ServerAlias localhost, richiesto per l’annullamento della validità della cache di Dispatcher.

Quando l’istanza Publish riceve una nuova versione di una pagina o di una risorsa dall’autore, utilizza l’agente di svuotamento per invalidare i percorsi appropriati nel proprio Dispatcher. Il percorso aggiornato viene rimosso dalla cache di Dispatcher, insieme ai relativi elementi principali, fino a un livello (puoi configurarlo con statfileslevel).

Annullamento esplicito della validità della cache di Dispatcher

L’Adobe consiglia di fare affidamento sulle intestazioni di cache standard per controllare il ciclo di vita della distribuzione dei contenuti. Tuttavia, se necessario, è possibile annullare la validità del contenuto direttamente in Dispatcher.

L’elenco seguente contiene scenari in cui potresti voler invalidare esplicitamente la cache (mentre facoltativamente stai in ascolto del completamento dell’invalidazione):

• Dopo la pubblicazione di contenuti come frammenti di esperienza o frammenti di contenuto, invalidando il contenuto pubblicato e memorizzato nella cache che fa riferimento a tali elementi.
• Notifica a un sistema esterno quando le pagine di riferimento sono state invalidate correttamente.

Esistono due approcci per invalidare esplicitamente la cache:

• L’approccio preferito è quello di utilizzare la Distribuzione dei contenuti Sling (SCD) dell’ambiente Author.
• Utilizzando l’API di replica per richiamare l’agente di svuotamento del Dispatcher per la pubblicazione.

Gli approcci sono diversi in termini di disponibilità dei livelli, possibilità di deduplicare gli eventi e garanzia di elaborazione degli eventi. La tabella seguente riassume queste opzioni:

Tieni presente che le due azioni direttamente correlate all’annullamento della validità della cache sono Invalidate API SCD (Sling Content Distribution) e Deactivate API della replica.

Inoltre, dalla tabella, si osserva che:

• L’API SCD è necessaria quando ogni evento deve essere garantito, ad esempio la sincronizzazione con un sistema esterno che richiede una conoscenza accurata. Se si verifica un evento di upscaling del livello di pubblicazione al momento della chiamata di invalidazione, viene generato un evento aggiuntivo quando ogni nuova pubblicazione elabora l’invalidazione.

• L’utilizzo dell’API di replica non è un caso d’uso comune, ma deve essere utilizzato nei casi in cui il trigger per invalidare la cache proviene dal livello di pubblicazione e non dal livello di authoring. Questo potrebbe essere utile se è configurato il TTL del dispatcher.

In conclusione, se desideri annullare la validità della cache di Dispatcher, l’opzione consigliata è quella di utilizzare l’azione Invalida API SCD di Author. Inoltre, puoi anche ascoltare l’evento in modo da attivare ulteriori azioni a valle.

Distribuzione dei contenuti Sling (SCD)

Quando utilizzi l’azione SCD di Author, il modello di implementazione è il seguente:

1. Dall’autore, scrivi il codice personalizzato per richiamare la distribuzione del contenuto sling API, passando l’azione di invalidazione con un elenco di percorsi:

@Reference
private Distributor distributor;

ResourceResolver resolver = ...; // the resource resolver used for authorizing the request
String agentName = "publish";    // the name of the agent used to distribute the request

String pathToInvalidate = "/content/to/invalidate";
DistributionRequest distributionRequest = new SimpleDistributionRequest(DistributionRequestType.INVALIDATE, false, pathToInvalidate);
distributor.distribute(agentName, resolver, distributionRequest);

• (Facoltativamente) Ascolta un evento che riflette la risorsa da invalidare per tutte le istanze di Dispatcher:

package org.apache.sling.distribution.journal.shared;

import org.apache.sling.discovery.DiscoveryService;
import org.apache.sling.distribution.journal.impl.event.DistributionEvent;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import static org.apache.sling.distribution.DistributionRequestType.INVALIDATE;
import static org.apache.sling.distribution.event.DistributionEventProperties.DISTRIBUTION_PATHS;
import static org.apache.sling.distribution.event.DistributionEventProperties.DISTRIBUTION_TYPE;
import static org.apache.sling.distribution.event.DistributionEventTopics.AGENT_PACKAGE_DISTRIBUTED;
import static org.osgi.service.event.EventConstants.EVENT_TOPIC;

@Component(immediate = true, service = EventHandler.class, property = {
        EVENT_TOPIC + "=" + AGENT_PACKAGE_DISTRIBUTED
})
public class InvalidatedHandler implements EventHandler {
    private static final Logger LOG = LoggerFactory.getLogger(InvalidatedHandler.class);

    @Reference
    private DiscoveryService discoveryService;

    @Override
    public void handleEvent(Event event) {

        String distributionType = (String) event.getProperty(DISTRIBUTION_TYPE);

        if (INVALIDATE.name().equals(distributionType)) {
            boolean isLeader = discoveryService.getTopology().getLocalInstance().isLeader();
            // process the OSGi event on the leader author instance
            if (isLeader) {
                String[] paths = (String[]) event.getProperty(DISTRIBUTION_PATHS);
                String packageId = (String) event.getProperty(DistributionEvent.PACKAGE_ID);
                invalidated(paths, packageId);
            }
        }
    }

    private void invalidated(String[] paths, String packageId) {
        // custom logic
        LOG.info("Successfully applied package with id {}, paths {}", packageId, paths);
    }
}

• (Facoltativamente) Eseguire la logica di business in invalidated(String[] paths, String packageId) metodo precedente.

API di replica

Di seguito è riportato il modello di implementazione per l’utilizzo dell’azione di disattivazione dell’API di replica:

1. Sul livello di pubblicazione, chiama l’API di replica per attivare l’agente di svuotamento del Dispatcher per la pubblicazione.

L’endpoint dell’agente di svuotamento non è configurabile, ma è preconfigurato per puntare a Dispatcher e corrisponde al servizio di pubblicazione in esecuzione insieme all’agente di svuotamento.

L’agente di svuotamento può in genere essere attivato da codice personalizzato basato su eventi o flussi di lavoro OSGi.

String[] paths = …
ReplicationOptions options = new ReplicationOptions();
options.setSynchronous(true);
options.setFilter( new AgentFilter {
  public boolean isIncluded (Agent agent) {
   return agent.getId().equals("flush");
  }
});

Replicator.replicate (session,ReplicationActionType.DELETE,paths, options);

Librerie lato client e coerenza delle versioni

Le pagine sono composte da HTML, JavaScript, CSS e immagini. I clienti sono incoraggiati a sfruttare Framework librerie lato client (clientlibs) per importare risorse JavaScript e CSS nelle pagine HTML, tenendo conto delle dipendenze tra le librerie JS.

Il framework clientlibs offre la gestione automatica delle versioni, il che significa che gli sviluppatori possono archiviare le modifiche alle librerie JS nel controllo del codice sorgente e che l’ultima versione sarà disponibile quando un cliente invia la propria versione. In caso contrario, gli sviluppatori dovranno modificare manualmente i HTML con riferimenti alla nuova versione della libreria, il che è particolarmente oneroso se molti modelli di HTML condividono la stessa libreria.

Quando vengono rilasciate in produzione le nuove versioni delle librerie, le pagine HTML di riferimento vengono aggiornate con nuovi collegamenti alle versioni aggiornate della libreria. Una volta scaduta la cache del browser per una determinata pagina HTML, non c’è alcun problema che le vecchie librerie vengano caricate dalla cache del browser, poiché ora la pagina aggiornata (da AEM) fa riferimento sempre alle nuove versioni delle librerie. In altre parole, una pagina HTML aggiornata includerà tutte le versioni più recenti della libreria.

Il meccanismo di ciò è un hash serializzato, che viene aggiunto al collegamento della libreria client, garantendo un URL univoco con versione affinché il browser possa memorizzare in cache i file CSS/JS. L’hash serializzato viene aggiornato solo quando cambia il contenuto della libreria client. Ciò significa che se si verificano aggiornamenti non correlati (ovvero, nessuna modifica ai css/js sottostanti della libreria client) anche con una nuova distribuzione, il riferimento rimane lo stesso, garantendo meno interruzioni alla cache del browser.

Abilitazione delle versioni Longcache delle librerie lato client: QuickStart per SDK as a Cloud Service per AEM

Le inclusioni clientlib predefinite in una pagina HTML hanno un aspetto simile al seguente:

<link rel="stylesheet" href="/etc.clientlibs/wkndapp/clientlibs/clientlib-base.css" type="text/css">

Quando è abilitato il controllo rigoroso delle versioni di clientlib, viene aggiunta una chiave hash a lungo termine come selettore alla libreria client. Di conseguenza, il riferimento clientlib è simile al seguente:

<link rel="stylesheet" href="/etc.clientlibs/wkndapp/clientlibs/clientlib-base.lc-7c8c5d228445ff48ab49a8e3c865c562-lc.css" type="text/css">

Il controllo delle versioni rigorose di clientlib è abilitato per impostazione predefinita in tutti gli ambienti AEM as a Cloud Service.

Per abilitare il controllo rigoroso delle versioni clientlib nel Quickstart dell’SDK locale, esegui le seguenti azioni:

1. Passa a Gestione configurazione OSGi <host>/system/console/configMgr
2. Trova la configurazione OSGi, ad Adobe Granite HTML Library Manager:
   • Seleziona la casella di controllo per abilitare il controllo delle versioni rigorose
   • Nel campo Chiave cache lato client a lungo termine, immetti il valore di /.*;hash
3. Salva le modifiche. Non è necessario salvare questa configurazione nel controllo del codice sorgente perché AEM as a Cloud Service la abilita automaticamente negli ambienti di sviluppo, stage e produzione.
4. Ogni volta che il contenuto della libreria client viene modificato, viene generata una nuova chiave hash e il riferimento HTML viene aggiornato.

Risorse Business.Adobe.com