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

Il presente documento presenta le linee guida per sviluppare su AEM as a Cloud Service e su importanti modi in cui differisce dall'AEM nei locali e dall'AEM nella 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 di pubblicazione deve garantire che tutti i dati che devono essere mantenuti vengano inviati a un servizio esterno per uno 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 non si tratta di un nuovo requisito per questo tipo di codice, nell’AEM as a Cloud Service è più probabile che si verifichi una rimozione dell’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 Processi Sling di pianificazione, in quanto ciò assicura di nuovo l’esecuzione di 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 il fornito Libreria Apache HttpComponents Client 4.x per effettuare 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 sul disco temporaneo del servizio AEM.

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

La replica inversa da Pubblica ad Autore 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 Publish e potenzialmente il cluster Author.

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

Il contenuto viene replicato dall’istanza di authoring a quella di pubblicazione 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 dei registri vengono scritte nei file locali in /crx-quickstart/logs cartella.

Negli ambienti Cloud, gli sviluppatori possono scaricare i registri tramite Cloud Manager o utilizzare uno strumento da 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, imposta /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 effettuare l’accesso 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.

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

Sviluppo locale local-development

Per lo sviluppo locale, gli sviluppatori hanno pieno accesso a CRXDE Liti (/crx/de) e la console web dell'AEM (/system/console).

Sullo sviluppo locale (utilizzando l’SDK), /apps e /libs può essere scritto direttamente in, il che è diverso dagli ambienti Cloud in cui tali cartelle di livello superiore 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. L’archivio immutabile (/libs, /apps) non può essere scritto in fase di runtime, pertanto se si tenta di farlo si verificheranno degli errori.

È invece possibile avviare il Browser dell’archivio dalla Console per sviluppatori as a Cloud Service dell’AEM, fornendo una visualizzazione in sola lettura nell’archivio per tutti gli ambienti sui livelli di authoring, pubblicazione e anteprima. Ulteriori informazioni sul Browser dell’archivio qui.

Nella Console per sviluppatori as a Cloud Service dell’AEM è disponibile un set di strumenti per il debug degli ambienti di sviluppo AEM as a Cloud Service per gli ambienti RDE, di sviluppo, di staging e di produzione. L’URL può essere determinato regolando gli URL del servizio Author o Publish come segue:

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

Per avviare la Console per sviluppatori as a Cloud Service AEM 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>

Consulta questa pagina per ulteriori informazioni.

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, la Console per sviluppatori as a Cloud Service dell’AEM dispone di un collegamento allo strumento Explain Query:

Per i programmi di produzione, l’accesso a Console per sviluppatori as a Cloud Service AEM è definito dal "Cloud Manager - Ruolo sviluppatore" in Adobe Admin Console, mentre per i programmi sandbox, la Console per sviluppatori as a Cloud Service AEM è disponibile per qualsiasi utente con un profilo di prodotto che 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, consulta 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 PUT /program/<program_id>/environment/<environment_id>/advancedNetworking regole di port forwarding dell'endpoint, che mappa la porta prevista (ad esempio, 465 o 587) su una porta proxy.

Si consiglia di configurare la rete avanzata con un kind parametro impostato su flexiblePortEgress poiché Adobe può ottimizzare le prestazioni del traffico in uscita dalla porta flessibile. Se è necessario un indirizzo IP in uscita univoco, scegli un kind parametro 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

Il Servizio Day CQ Mail OSGI Le e-mail devono essere inviate 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 Day CQ Mail Service Servizio OSGi.

Consulta la Documentazione di AEM 6.5 per informazioni dettagliate sulla configurazione delle impostazioni e-mail. Per AEM as a Cloud Service, si noti che i seguenti adeguamenti necessari com.day.cq.mailer.DefaultMailService OSGI servizio:

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

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

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

Il smtp.starttls La proprietà verrà impostata automaticamente dall’AEM as a Cloud Service in fase di runtime 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. Questo indipendentemente dal smtp.starttls valori impostati nella configurazione OSGI.

Il servizio di posta può essere configurato facoltativamente con il supporto OAuth2. Per ulteriori informazioni, consulta 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. Osservare le seguenti modifiche necessarie alla com.day.cq.mailer.DefaultMailService OSGI servizio:

AEM as a Cloud Service richiede che la posta venga inviata attraverso 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:

Il smtp.starttls La proprietà verrà impostata automaticamente dall’AEM as a Cloud Service in fase di runtime 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. Questo indipendentemente dal smtp.starttls valori 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 l’AEM as a Cloud Service non è destinato all’utilizzo 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

Consulta la Documentazione di Apache Oak per ulteriori dettagli.

Assets linee guida per lo sviluppo e casi di utilizzo use-cases-assets

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