Linee guida per lo sviluppo in AEM as a Cloud Service aem-as-a-cloud-service-development-guidelines

Questo documento presenta le linee guida per lo sviluppo su AEM as a Cloud Service e sulle differenze importanti tra AEM on-premise e AEM in AMS.

Il Codice Deve Essere Basato Su Cluster cluster-aware

Il codice in esecuzione in AEM as a Cloud Service deve tenere presente che è sempre in esecuzione in un cluster. Ciò significa che sono sempre in esecuzione più istanze. Il codice deve essere resiliente, in particolare in quanto un’istanza potrebbe essere arrestata in qualsiasi momento.

Durante l’aggiornamento di AEM as a Cloud Service, sono presenti istanze con codice vecchio e nuovo in esecuzione in parallelo. Pertanto, il vecchio codice non deve interrompere il contenuto creato dal nuovo codice e il nuovo codice deve essere in grado di gestire il contenuto vecchio.

Se è necessario identificare l’elemento primario nel cluster, è possibile utilizzare l’API di individuazione Apache Sling per rilevarlo.

Stato in memoria state-in-memory

Lo stato non deve essere mantenuto in memoria, ma deve essere mantenuto nell’archivio. In caso contrario, questo stato potrebbe andare perduto se un’istanza viene arrestata.

Stato nel file system state-on-the-filesystem

Non utilizzare il file system dell’istanza in AEM as a Cloud Service. Il disco è temporaneo e viene eliminato quando le istanze vengono riciclate. È possibile un uso limitato del file system per la memorizzazione temporanea in relazione al trattamento di singole richieste, ma non dovrebbe essere utilizzato impropriamente per file di grandi dimensioni. Questo perché potrebbe avere un impatto negativo sulla quota di utilizzo delle risorse ed essere soggetto a limitazioni del disco.

Ad esempio, se l'utilizzo del file system non è supportato, il livello Publish deve garantire che tutti i dati che devono essere mantenuti vengano inviati a un servizio esterno per lo storage a lungo termine.

Osservazione observation

Allo stesso modo, con tutto ciò che accade in modo asincrono come agire su eventi di osservazione, non si può garantire che venga eseguito localmente e quindi deve essere utilizzato con cautela. Questo vale sia per gli eventi JCR che per gli eventi della risorsa Sling. Nel momento in cui si verifica una modifica, l’istanza può essere rimossa e sostituita da un’istanza diversa. Altre istanze della topologia attive in quel momento sono in grado di reagire a quell'evento. In questo caso, tuttavia, non si tratterà di un evento locale e potrebbe addirittura non esserci un leader attivo nel caso in cui, al momento dell'evento, si proceda alle elezioni per il leader.

Attività in background e processi con esecuzione prolungata background-tasks-and-long-running-jobs

Il codice eseguito come attività in background deve presupporre che l’istanza in cui viene eseguito possa essere disattivata in qualsiasi momento. Pertanto, il codice deve essere resiliente e soprattutto ripristinabile. Ciò significa che se il codice viene rieseguito, non dovrebbe iniziare di nuovo dall’inizio, ma piuttosto vicino a da dove si è interrotto. Anche se questo non è un nuovo requisito per questo tipo di codice, in AEM as a Cloud Service è più probabile che venga eliminata un’istanza.

Per ridurre al minimo i problemi, è necessario evitare, se possibile, processi con tempi di esecuzione lunghi, che dovrebbero essere almeno ripristinabili. Per eseguire tali processi, utilizza Sling Jobs, che dispongono di una garanzia almeno una volta e quindi, se vengono interrotti, verranno rieseguiti il prima possibile. Ma probabilmente non dovrebbero ricominciare dall'inizio. Per la pianificazione di tali processi, è consigliabile utilizzare la pianificazione Processi Sling, in quanto garantisce l'esecuzione almeno una volta.

Non utilizzare Sling Commons Scheduler per la pianificazione in quanto l’esecuzione non può essere garantita. È solo più probabile che sia programmato.

Allo stesso modo, con tutto ciò che accade in modo asincrono, come agire su eventi di osservazione (che si tratti di eventi JCR o di eventi di risorse Sling), non può essere garantito che venga eseguito e pertanto deve essere utilizzato con cautela. Questo è già vero per le implementazioni AEM nel presente.

Connessioni HTTP in uscita outgoing-http-connections

Si consiglia vivamente che tutte le connessioni HTTP in uscita impostino timeout ragionevoli di connessione e lettura; i valori consigliati sono 1 secondo per il timeout di connessione e 5 secondi per il timeout di lettura. I numeri esatti devono essere determinati in base alle prestazioni del sistema back-end che gestisce queste richieste.

Per il codice che non applica questi timeout, le istanze AEM in esecuzione su AEM as a Cloud Service applicheranno un timeout globale. Questi valori di timeout sono di 10 secondi per le chiamate di connessione e di 60 secondi per le chiamate di lettura per le connessioni.

L'Adobe consiglia di utilizzare la libreria Apache HttpComponents Client 4.x fornita per creare connessioni HTTP.

Le alternative che sono note per funzionare, ma che possono richiedere di fornire personalmente la dipendenza sono:

Oltre a fornire timeout, è necessario anche gestire correttamente tali timeout e inserire codici di stato HTTP imprevisti.

Gestione dei limiti di velocità delle richieste rate-limit-handling

Quando la frequenza delle richieste in entrata all’AEM supera i livelli integri, l’AEM risponde alle nuove richieste con il codice di errore HTTP 429. Le applicazioni che effettuano chiamate programmatiche all'AEM possono considerare la codifica in modo difensivo, ritentando dopo alcuni secondi con una strategia di backoff esponenziale. Prima di metà agosto 2023, l’AEM ha risposto alla stessa condizione con il codice di errore HTTP 503.

Nessuna personalizzazione interfaccia classica no-classic-ui-customizations

AEM as a Cloud Service supporta solo l’interfaccia utente touch per il codice cliente di terze parti. L’interfaccia classica non è disponibile per la personalizzazione.

Nessuna libreria nativa o binaria nativa avoid-native-binaries

Le librerie e i file binari nativi non devono essere distribuiti o installati in ambienti cloud.

Inoltre, il codice non deve tentare di scaricare file binari nativi o estensioni Java native (ad esempio, JNI) in fase di esecuzione.

Nessun file binario di streaming tramite AEM as a Cloud Service no-streaming-binaries

I dati binari sono accessibili tramite la rete CDN, che fornisce dati binari al di fuori dei servizi AEM di base.

Ad esempio, non utilizzare asset.getOriginal().getStream(), che attiva il download di un binario nel disco temporaneo del servizio AEM.

Nessun agente di replica inversa no-reverse-replication-agents

La replica inversa da Publish all’istanza di authoring non è supportata in AEM as a Cloud Service. Se tale strategia è necessaria, puoi utilizzare un archivio di persistenza esterno condiviso tra la farm delle istanze di Publish e potenzialmente il cluster Author.

È possibile che gli agenti di replica di inoltro debbano essere trasferiti forward-replication-agents

Il contenuto viene replicato da Author a Publish tramite un meccanismo pub-sub. Gli agenti di replica personalizzati non sono supportati.

Nessun overload degli ambienti di sviluppo overloading-dev-envs

Gli ambienti di produzione sono dimensionati più in alto per garantire un funzionamento stabile, mentre gli ambienti di staging sono dimensionati come gli ambienti di produzione per garantire test realistici in condizioni di produzione.

Gli ambienti di sviluppo e gli ambienti di sviluppo rapido devono essere limitati allo sviluppo, all’analisi degli errori e ai test funzionali e non devono essere progettati per elaborare carichi di lavoro elevati né grandi quantità di contenuti.

Ad esempio, la modifica della definizione di un indice in un archivio di contenuti di grandi dimensioni in un ambiente di sviluppo può causare la reindicizzazione, con conseguente elaborazione eccessiva. I test che richiedono contenuti sostanziali devono essere eseguiti in ambienti di staging.

Monitoraggio e debug monitoring-and-debugging

Registri logs

Per lo sviluppo locale, le voci di registro vengono scritte nei file locali nella cartella /crx-quickstart/logs.

Negli ambienti Cloud, gli sviluppatori possono scaricare i registri tramite Cloud Manager o utilizzare uno strumento della riga di comando per visualizzare i registri.

Impostazione del livello di registro

Per modificare i livelli di registro per gli ambienti Cloud, è necessario modificare la configurazione OSGI Sling Logging, seguita da una ridistribuzione completa. Poiché non è istantaneo, presta attenzione quando abiliti registri dettagliati in ambienti di produzione che ricevono molto traffico. In futuro, è possibile che esistano meccanismi per modificare più rapidamente il livello del registro.

Attivazione del livello di registro DEBUG

Il livello di registro predefinito è INFO, ovvero i messaggi DEBUG non vengono registrati. Per attivare il livello di registro DEBUG, aggiorna la seguente proprietà in modalità di debug.

/libs/sling/config/org.apache.sling.commons.log.LogManager/org.apache.sling.commons.log.level

Ad esempio, impostare /apps/<example>/config/org.apache.sling.commons.log.LogManager.factory.config~<example>.cfg.json con il seguente valore.

{
   "org.apache.sling.commons.log.names": [
      "com.example"
   ],
   "org.apache.sling.commons.log.level": "DEBUG",
   "org.apache.sling.commons.log.file": "logs/error.log",
   "org.apache.sling.commons.log.additiv": "false"
}

Non lasciare il registro a livello di registro DEBUG più a lungo del necessario, in quanto questo genera un numero elevato di voci.

È possibile impostare livelli di registro discreti per i diversi ambienti AEM utilizzando il targeting di configurazione OSGi basato sulla modalità di esecuzione, se è consigliabile registrare sempre a DEBUG durante lo sviluppo. Ad esempio:

Una riga nel file di debug in genere inizia con DEBUG e quindi fornisce il livello di registro, l'azione del programma di installazione e il messaggio di registro. Ad esempio:

DEBUG 3 WebApp Panel: WebApp successfully deployed

I livelli del registro sono i seguenti:

Immagini thread thread-dumps

Le immagini thread negli ambienti Cloud vengono raccolte su base continuativa, ma al momento non possono essere scaricate in modo autonomo. Nel frattempo, contatta il supporto AEM se sono necessarie immagini thread per il debug di un problema, specificando l’intervallo di tempo esatto.

CRX/DE Lite e AEM as a Cloud Service Developer Console crxde-lite-and-developer-console

Sviluppo locale local-development

Per lo sviluppo locale, gli sviluppatori hanno accesso completo a CRXDE Lite (/crx/de) e alla console Web AEM (/system/console).

Nello sviluppo locale (utilizzando l'SDK), /apps e /libs possono essere scritti direttamente in, il che è diverso dagli ambienti Cloud in cui le cartelle di primo livello non sono modificabili.

Strumenti di sviluppo in AEM as a Cloud Service aem-as-a-cloud-service-development-tools

I clienti possono accedere a CRXDE lite nell’ambiente di sviluppo del livello di authoring, ma non in quello di stage o produzione. Impossibile scrivere nell'archivio immutabile (/libs, /apps) in fase di esecuzione. Se si tenta di eseguire questa operazione, verranno generati errori.

È invece possibile avviare il Browser dell’archivio da AEM as a Cloud Service Developer Console, fornendo una vista in sola lettura nell’archivio per tutti gli ambienti sui livelli di authoring, pubblicazione e anteprima. Per ulteriori informazioni, vedere Browser repository.

In AEM as a Cloud Service Developer Console sono disponibili una serie di strumenti per il debug degli ambienti di sviluppo AEM as a Cloud Service per gli ambienti RDE, di sviluppo, di stage e di produzione. L’URL può essere determinato regolando gli URL del servizio Author o Publish nel modo seguente:

https://dev-console/-<namespace>.<cluster>.dev.adobeaemcloud.com

Per avviare AEM as a Cloud Service Developer Console in base a un parametro di ambiente descritto di seguito, è possibile utilizzare il seguente comando CLI di Cloud Manager:

aio cloudmanager:open-developer-console <ENVIRONMENTID> --programId <PROGRAMID>

Per ulteriori informazioni, vedere Informazioni sulla versione.

Gli sviluppatori possono generare informazioni sullo stato e risolvere varie risorse.

Come illustrato di seguito, le informazioni sugli stati disponibili includono lo stato di bundle, componenti, configurazioni OSGI, indici Oak, servizi OSGI e processi Sling.

Come illustrato di seguito, gli sviluppatori possono risolvere le dipendenze dei pacchetti e i servlet:

Utile anche per il debug, AEM as a Cloud Service Developer Console dispone di un collegamento allo strumento Explain Query:

Per i programmi di produzione, l’accesso a AEM as a Cloud Service Developer Console è definito dal "Cloud Manager - Ruolo Sviluppatore" in Adobe Admin Console, mentre per i programmi sandbox, AEM as a Cloud Service Developer Console è disponibile per qualsiasi utente con un profilo di prodotto che gli consente di accedere a AEM as a Cloud Service. Per tutti i programmi, è necessario "Cloud Manager - Ruolo Sviluppatore" per le immagini di stato e il browser dell’archivio e gli utenti devono essere definiti anche nel profilo di prodotto Utenti AEM o Amministratori AEM sui servizi di authoring e pubblicazione per visualizzare i dati di entrambi i servizi. Per ulteriori informazioni sulla configurazione delle autorizzazioni utente, vedere Documentazione di Cloud Manager.

Monitoraggio delle prestazioni performance-monitoring

Adobe monitora le prestazioni delle applicazioni e adotta misure per affrontare eventuali deterioramenti. Al momento, non è possibile osservare le metriche delle applicazioni.

Invio e-mail sending-email

Le sezioni seguenti descrivono come richiedere, configurare e inviare e-mail.

Abilitazione dell’e-mail in uscita enabling-outbound-email

Per impostazione predefinita, le porte utilizzate per l’invio delle e-mail sono disabilitate. Per attivare una porta, configurare rete avanzata, assicurandosi di impostare per ogni ambiente necessario le regole di port forwarding dell'endpoint PUT /program/<program_id>/environment/<environment_id>/advancedNetworking, che mappa la porta prevista (ad esempio, 465 o 587) su una porta proxy.

È consigliabile configurare la rete avanzata con un parametro kind impostato su flexiblePortEgress poiché Adobe può ottimizzare le prestazioni del traffico in uscita dalla porta flessibile. Se è necessario un indirizzo IP in uscita univoco, scegliere un parametro kind di dedicatedEgressIp. Se hai già configurato la VPN per altri motivi, puoi utilizzare anche l’indirizzo IP univoco fornito dalla variante di rete avanzata.

È necessario inviare messaggi di posta elettronica tramite un server di posta anziché direttamente ai client di posta elettronica. In caso contrario, le e-mail potrebbero essere bloccate.

Invio di e-mail sending-emails

Utilizzare il servizio OSGI 🔗 del servizio di posta CQ di Day e inviare le e-mail al server di posta indicato nella richiesta di supporto anziché direttamente ai destinatari.

Configurazione email-configuration

Le e-mail in AEM devono essere inviate utilizzando il servizio OSGi del servizio di posta CQ Day.

Per informazioni dettagliate sulla configurazione delle impostazioni e-mail, consulta la documentazione di AEM 6.5. Per AEM as a Cloud Service, prendere nota delle seguenti modifiche necessarie al servizio com.day.cq.mailer.DefaultMailService OSGI:

La porta del server SMTP deve essere impostata come valore portDest impostato nel parametro portForwards utilizzato nella chiamata API durante la configurazione della rete avanzata e il valore portOrig deve essere un valore significativo compreso nell'intervallo richiesto 30000 - 30999. Ad esempio, se la porta del server SMTP è 465, la porta 30465 deve essere utilizzata come valore portOrig.

In questo caso, supponendo che SSL debba essere abilitato, nella configurazione del servizio OSGI del servizio di posta CQ Day :

In alternativa, se la porta di destinazione è 587, è necessario utilizzare un valore portOrig di 30587. E supponendo che SSL sia disabilitato, la configurazione del servizio OSGI Day CQ Mail Service:

La proprietà smtp.starttls verrà impostata automaticamente da AEM as a Cloud Service in fase di esecuzione su un valore appropriato. Pertanto, se smtp.ssl è impostato su true, smtp.startls viene ignorato. Se smtp.ssl è impostato su false, smtp.starttls è impostato su true. Indipendentemente dai valori smtp.starttls impostati nella configurazione OSGI.

Il servizio di posta può essere configurato facoltativamente con il supporto OAuth2. Per ulteriori informazioni, vedere Supporto OAuth2 per il servizio di posta.

Configurazione e-mail legacy legacy-email-configuration

Prima della versione 2021.9.0, l’e-mail era configurata tramite una richiesta di assistenza clienti. Prendere nota delle seguenti modifiche necessarie al servizio com.day.cq.mailer.DefaultMailService OSGI:

AEM as a Cloud Service richiede che la posta venga inviata tramite la porta 465. Se un server di posta non supporta la porta 465, è possibile utilizzare la porta 587 purché sia abilitata l’opzione TLS.

Se è stata richiesta la porta 465:

e se è stata richiesta la porta 587:

La proprietà smtp.starttls verrà impostata automaticamente da AEM as a Cloud Service in fase di esecuzione su un valore appropriato. Pertanto, se smtp.ssl è impostato su true, smtp.startls viene ignorato. Se smtp.ssl è impostato su false, smtp.starttls è impostato su true. Indipendentemente dai valori smtp.starttls impostati nella configurazione OSGI.

L'host del server SMTP deve essere impostato su quello del server di posta.

Evita Proprietà Con Più Valori Di Grandi Dimensioni avoid-large-mvps

L’archivio dei contenuti Oak sottostante ad AEM as a Cloud Service non deve essere utilizzato con un numero eccessivo di proprietà con più valori (MVP). Una regola empirica è mantenere gli MVP al di sotto di 1000. Tuttavia, le prestazioni effettive dipendono da molti fattori.

Gli avvisi vengono registrati per impostazione predefinita dopo il superamento di 1000. Sono simili alle seguenti.

org.apache.jackrabbit.oak.jcr.session.NodeImpl Large multi valued property [/path/to/property] detected (1029 values).

Gli MVP di grandi dimensioni possono causare errori dovuti al fatto che il documento MongoDB supera i 16 MB, con conseguente errore simile al seguente.

Caused by: com.mongodb.MongoWriteException: Resulting document after update is larger than 16777216

Per ulteriori dettagli, consulta la documentazione di Apache Oak.

Assets linee guida per lo sviluppo e casi d'uso use-cases-assets

Per informazioni sui casi d'uso per lo sviluppo, le raccomandazioni e il materiale di riferimento per Assets as a Cloud Service, consulta Riferimenti per sviluppatori per Assets.