AEM riktlinjer för as a Cloud Service utveckling aem-as-a-cloud-service-development-guidelines
I det här dokumentet presenteras riktlinjer för utveckling på AEM as a Cloud Service och viktiga sätt som skiljer sig från AEM på plats och AEM i AMS.
Koden måste vara klustermedveten cluster-aware
Kod som körs AEM as a Cloud Service måste vara medveten om att den alltid körs i ett kluster. Det innebär att fler än en instans alltid körs. Koden måste vara flexibel, särskilt eftersom en instans kan stoppas när som helst.
Under uppdateringen av AEM as a Cloud Service finns det instanser där gammal och ny kod körs parallellt. Därför får gammal kod inte bryta med innehåll som skapas av ny kod och ny kod måste kunna hantera gammalt innehåll.
Om det finns ett behov av att identifiera det primära klustret kan API:t för identifiering av Apache Sling användas för att identifiera det.
Läge i minnet state-in-memory
Tillståndet får inte sparas i minnet utan sparas i databasen. Annars kan det här läget gå förlorat om en instans stoppas.
Läge i filsystemet state-on-the-filesystem
Använd inte instansens filsystem AEM as a Cloud Service. Disken är tillfällig och kasseras när instanser återvinns. Det är möjligt att använda filsystemet i begränsad omfattning för tillfällig lagring i samband med behandling av enstaka begäranden, men det bör inte missbrukas för stora filer. Detta beror på att det kan ha en negativ inverkan på resursanvändningskvoten och leda till diskbegränsningar.
Som ett exempel där filsystemsanvändningen inte stöds bör publiceringsskiktet se till att alla data som måste vara beständiga skickas till en extern tjänst för längre lagringstid.
Observera observation
På samma sätt kan man inte garantera att allt som sker asynkront, som att agera på observationshändelser, utförs lokalt och därför måste användas med försiktighet. Detta gäller både JCR-händelser och Sling-resurshändelser. När en ändring inträffar kan instansen tas ned och ersättas av en annan instans. Andra instanser i topologin som är aktiva vid den tidpunkten kan reagera på den händelsen. I det här fallet kommer detta dock inte att vara en lokal händelse och det kanske inte ens finns någon aktiv ledare i händelse av ett pågående ledarval när evenemanget utställs.
Bakgrundsuppgifter och tidskrävande jobb background-tasks-and-long-running-jobs
Kod som körs som en bakgrundsuppgift måste anta att instansen som den körs i när som helst kan tas ned. Därför måste koden vara flexibel och viktigast av allt återtagbar. Det innebär att om koden körs igen ska den inte börja om från början, utan i närheten av den plats där den slutade. Även om detta inte är ett nytt krav för den här typen av kod är det AEM as a Cloud Service mer sannolikt att en instans kommer att tas bort.
För att minimera problemet bör långvariga jobb om möjligt undvikas, och de bör kunna återställas till ett minimum. För att utföra sådana jobb använder du Sling Jobs, som har en garanti som är minst en gång och därför, om de avbryts, kommer att köras igen så snart som möjligt. Men de borde förmodligen inte börja från början igen. För schemaläggning av sådana jobb är det bäst att använda Försäljningsjobb schemaläggaren på samma sätt säkerställer körningen minst en gång.
Använd inte Sling Commons Scheduler för schemaläggning eftersom körning inte kan garanteras. Det är troligare att det är planerat.
På samma sätt kan man inte garantera att allt som sker asynkront, som att agera på observationshändelser (som JCR-händelser eller Sling-resurshändelser), utförs och därför måste användas med försiktighet. Detta gäller redan för AEM distributioner i det här läget.
Utgående HTTP-anslutningar outgoing-http-connections
Vi rekommenderar starkt att alla utgående HTTP-anslutningar anger rimliga anslutnings- och lästimeout. Föreslagna värden är 1 sekund för anslutningstimeout och 5 sekunder för lästimeout. De exakta numren måste bestämmas utifrån hur väl serverdelssystemet hanterar dessa begäranden.
För kod som inte tillämpar dessa tidsgränser kommer AEM instanser som körs på AEM as a Cloud Service att tillämpa en global tidsgräns. Dessa timeoutvärden är 10 sekunder för anslutningsanrop och 60 sekunder för läsanrop för anslutningar.
Adobe rekommenderar att du använder Bibliotek för Apache HttpComponents Client 4.x för att skapa HTTP-anslutningar.
Alternativ som är kända för att fungera, men som kan kräva att du själv anger beroendet är:
- java.net.URL och/eller java.net.URLConnection (tillhandahålls av AEM)
- Apache Commons HttpClient 3.x (rekommenderas inte eftersom den är inaktuell och ersatt av version 4.x)
- OK HTTP (Tillhandahålls inte av AEM)
Förutom att tillhandahålla timeout bör även en korrekt hantering av sådana tidsgränser och oväntade HTTP-statuskoder implementeras.
Hantera hastighetsbegränsningar för begäranden rate-limit-handling
När antalet inkommande begäranden som ska AEM överstiger felfria nivåer, svarar AEM på nya begäranden med HTTP-felkod 429. Program som anropar programmatiska AEM kan överväga att koda på ett defensivt sätt och försöka igen efter några sekunder med en exponentiell bakåtstrategi. Före mitten av augusti 2023 svarade AEM på samma villkor med HTTP-felkod 503.
Inga klassiska gränssnittsanpassningar no-classic-ui-customizations
AEM as a Cloud Service stöder bara Touch-gränssnittet för kundkod från tredje part. Klassiskt användargränssnitt är inte tillgängligt för anpassning.
Inga inbyggda binärfiler eller inbyggda bibliotek avoid-native-binaries
Inbyggda binära filer och bibliotek får inte distribueras till eller installeras i molnmiljöer.
Koden bör inte heller försöka hämta inbyggda binära filer eller inbyggda Java-tillägg (till exempel JNI) vid körning.
Inga bindningar för direktuppspelning via AEM as a Cloud Service no-streaming-binaries
Binärfiler bör nås via CDN, som kommer att betjäna binärfiler utanför de centrala AEM.
Använd till exempel inte asset.getOriginal().getStream()
, som startar nedladdningen av en binärfil till AEM.
Inga omvända replikeringsagenter no-reverse-replication-agents
Omvänd replikering från Publicera till Författare stöds inte i AEM as a Cloud Service. Om en sådan strategi behövs kan du använda ett externt beständigt arkiv som delas mellan gruppen med publiceringsinstanser och eventuellt klustret Författare.
Vidarebefordra replikeringsagenter kan behöva porteras forward-replication-agents
Innehållet replikeras från författare till publicering via en pub-sub-mekanism. Anpassade replikeringsagenter stöds inte.
Inga överbelastade utvecklingsmiljöer overloading-dev-envs
Produktionsmiljöerna storleksanpassas högre för att säkerställa stabil drift, medan scenmiljöer storleksförändras som produktionsmiljöer för att säkerställa realistisk testning under produktionsförhållanden.
Utvecklingsmiljöer och Rapid Dev-miljöer bör begränsas till utveckling, felanalys och funktionstester, och är inte utformade för att bearbeta stora arbetsbelastningar eller stora mängder innehåll.
Om du till exempel ändrar en indexdefinition i en databas med stort innehåll i en Dev-miljö kan det leda till omindexering, vilket resulterar i för mycket bearbetning. Tester som kräver omfattande innehåll bör köras på scenmiljöer.
Övervakning och felsökning monitoring-and-debugging
Loggar logs
För lokal utveckling skrivs loggposterna till lokala filer i /crx-quickstart/logs
mapp.
I molnmiljöer kan utvecklare hämta loggar via Cloud Manager eller använda ett kommandoradsverktyg för att avsluta loggarna.
Ange loggnivå
Om du vill ändra loggnivåerna för molnmiljöer bör du ändra Sling Logging OSGI-konfigurationen, följt av en fullständig omdistribution. Eftersom detta inte är omedelbart, var försiktig med att aktivera utförliga loggar i produktionsmiljöer som tar emot mycket trafik. I framtiden kan det finnas mekanismer som gör att loggnivån kan ändras snabbare.
Aktivera loggnivån för FELSÖKNING
Standardloggnivån är INFO, d.v.s. DEBUG-meddelanden loggas inte. Om du vill aktivera DEBUG-loggnivån uppdaterar du följande egenskap till felsökningsläge.
/libs/sling/config/org.apache.sling.commons.log.LogManager/org.apache.sling.commons.log.level
Ange till exempel /apps/<example>/config/org.apache.sling.commons.log.LogManager.factory.config~<example>.cfg.json
med följande värde.
{
"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"
}
Lämna inte loggen på DEBUG-loggnivån längre än nödvändigt eftersom detta genererar många poster.
Du kan ange diskreta loggnivåer för olika AEM miljöer med hjälp av OSGi-konfigurationsinriktning som baseras på körningsläge om det är önskvärt att alltid logga in DEBUG
under utvecklingen. Till exempel:
org.apache.sling.commons.log.level
egenskapsvärdeEn rad i felsökningsfilen börjar oftast med DEBUG och anger sedan loggnivån, installationsåtgärden och loggmeddelandet. Till exempel:
DEBUG 3 WebApp Panel: WebApp successfully deployed
Loggnivåerna är följande:
Trådbitar thread-dumps
Tråddumpar i molnmiljöer samlas in kontinuerligt, men kan för närvarande inte hämtas på ett självbetjäningssätt. Under tiden kontaktar du AEM om det behövs tråddumpar för att felsöka ett problem och ange exakt tidsfönster.
CRX/DE Lite och AEM as a Cloud Service Developer Console crxde-lite-and-developer-console
Lokal utveckling local-development
För lokal utveckling har utvecklare full tillgång till CRXDE Lite (/crx/de
) och AEM webbkonsol (/system/console
).
Lokal utveckling (med SDK) /apps
och /libs
kan skrivas direkt, vilket skiljer sig från molnmiljöer där mapparna på den översta nivån inte kan ändras.
AEM as a Cloud Service utvecklingsverktyg aem-as-a-cloud-service-development-tools
Kunderna har tillgång till CRXDE-klassen i utvecklingsmiljön, men inte i fas eller produktion. Oändringsbar databas (/libs
, /apps
) kan inte skrivas till vid körning, så om du försöker göra det uppstår fel.
I stället kan databasläsaren startas från den AEM as a Cloud Service utvecklarkonsolen, vilket ger en skrivskyddad vy i databasen för alla miljöer med författare, publicering och förhandsgranskningsnivåer. Läs mer om Databasläsaren här.
En uppsättning verktyg för felsökning AEM as a Cloud Service utvecklingsmiljöer finns på AEM as a Cloud Service Developer Console för RDE-, dev-, stage- och produktionsmiljöer. URL:en kan bestämmas genom att ändra författarens eller publiceringstjänstens URL:er enligt följande:
https://dev-console/-<namespace>.<cluster>.dev.adobeaemcloud.com
Följande CLI-kommando för Cloud Manager kan användas som en genväg för att starta den AEM as a Cloud Service utvecklarkonsolen baserat på en miljöparameter som beskrivs nedan:
aio cloudmanager:open-developer-console <ENVIRONMENTID> --programId <PROGRAMID>
Se den här sidan för mer information.
Utvecklare kan generera statusinformation och lösa olika resurser.
Som framgår nedan omfattar tillgänglig statusinformation status för paket, komponenter, OSGI-konfigurationer, ekindex, OSGI-tjänster och Sling-jobb.
Som framgår nedan kan utvecklare lösa paketberoenden och -servrar:
Den AEM as a Cloud Service utvecklarkonsolen är också användbar för felsökning och har en länk till verktyget Förklara fråga:
För produktionsprogram definieras åtkomsten till den AEM as a Cloud Service utvecklarkonsolen av"Cloud Manager - utvecklarrollen" i Adobe Admin Console, medan den AEM as a Cloud Service utvecklarkonsolen är tillgänglig för alla användare med en produktprofil som ger dem tillgång till AEM as a Cloud Service för sandlådeprogram. För alla program krävs"Cloud Manager - Developer Role" för statusdumpar och databasens webbläsare och användare måste också definieras i produktprofilen AEM användare eller AEM administratörer för både författar- och publiceringstjänster för att visa data från båda tjänsterna. Mer information om hur du ställer in användarbehörigheter finns i Dokumentation för Cloud Manager.
Prestandaövervakning performance-monitoring
Adobe övervakar programmets prestanda och vidtar åtgärder för att hantera om en försämring observeras. För närvarande kan inte tillämpningsmetrierna följas.
Skickar e-post sending-email
Avsnitten nedan beskriver hur du begär, konfigurerar och skickar e-post.
Aktivera utgående e-post enabling-outbound-email
Portar som används för att skicka e-post är som standard inaktiverade. Om du vill aktivera en port konfigurerar du avancerat nätverkoch se till att du för varje miljö som behövs anger PUT /program/<program_id>/environment/<environment_id>/advancedNetworking
slutpunktens regler för portvidarebefordran, som mappar den avsedda porten (till exempel 465 eller 587) till en proxyport.
Vi rekommenderar att du konfigurerar avancerade nätverk med kind
parametern inställd på flexiblePortEgress
eftersom Adobe kan optimera prestandan för flexibel trafik i hamnutgångar. Om en unik IP-adress för utgångar krävs väljer du en kind
parameter för dedicatedEgressIp
. Om du redan har konfigurerat VPN av andra skäl kan du även använda den unika IP-adressen som den avancerade nätverksvarianten ger.
Du måste skicka e-post via en e-postserver i stället för direkt till e-postklienter. Annars kan e-postmeddelandena vara blockerade.
Skicka e-post sending-emails
The Day CQ Mail Service OSGI Service ska användas och e-post måste skickas till den e-postserver som anges i supportförfrågan i stället för direkt till mottagarna.
Konfiguration email-configuration
E-post i AEM ska skickas med Day CQ Mail Service OSGi-tjänst.
Se AEM 6.5-dokumentation om du vill ha mer information om hur du konfigurerar e-postinställningar. Observera följande nödvändiga justeringar för AEM as a Cloud Service com.day.cq.mailer.DefaultMailService OSGI
tjänst:
- SMTP-serverns värdnamn ska anges till $[env:AEM_PROXY_HOST;default=proxy.tunnel]
- SMTP-serverporten ska anges till värdet för den ursprungliga proxyporten som angetts i parametern portForwards som används i API-anropet när avancerade nätverk konfigureras. Exempel: 30465 (i stället för 465)
SMTP-serverporten ska anges som portDest
värdet som anges i parametern portForwards som används i API-anropet när avancerade nätverk konfigureras och portOrig
ska vara ett meningsfullt värde som ligger inom intervallet 30000-30999. Om till exempel SMTP-serverporten är 465 bör port 30465 användas som portOrig
värde.
I det här fallet, och under förutsättning att SSL måste aktiveras, i konfigurationen av Day CQ Mail Service OSGI tjänst:
- Ange
smtp.port
till30465
- Ange
smtp.ssl
tilltrue
Om målporten är 587 kan du även portOrig
Värdet 30587 bör användas. Om SSL ska vara inaktiverat, konfigureras tjänsten Dag CQ Mail Service OSGI:
- Ange
smtp.port
till30587
- Ange
smtp.ssl
tillfalse
The smtp.starttls
egenskapen ställs automatiskt in av AEM as a Cloud Service vid körning till ett lämpligt värde. Om smtp.ssl
är inställt på true, smtp.startls
ignoreras. If smtp.ssl
är inställt på false, smtp.starttls
är inställt på true. Detta är oberoende av smtp.starttls
värden som anges i OSGI-konfigurationen.
E-posttjänsten kan även konfigureras med OAuth2-stöd. Mer information finns i OAuth2-stöd för e-posttjänsten.
Äldre e-postkonfiguration legacy-email-configuration
Före version 2021.9.0 konfigurerades e-postmeddelandet via en kundsupportförfrågan. Observera följande nödvändiga justeringar i com.day.cq.mailer.DefaultMailService OSGI
tjänst:
AEM as a Cloud Service kräver att e-post skickas via port 465. Om en e-postserver inte stöder port 465 kan port 587 användas så länge som TLS-alternativet är aktiverat.
Om port 465 har begärts:
- set
smtp.port
till465
- set
smtp.ssl
tilltrue
och om port 587 har begärts:
- set
smtp.port
till587
- set
smtp.ssl
tillfalse
The smtp.starttls
egenskapen ställs automatiskt in av AEM as a Cloud Service vid körning till ett lämpligt värde. Om smtp.ssl
är inställt på true, smtp.startls
ignoreras. If smtp.ssl
är inställt på false, smtp.starttls
är inställt på true. Detta är oberoende av smtp.starttls
värden som anges i OSGI-konfigurationen.
SMTP-servervärden ska vara samma som e-postservern.
Undvik stora flervärdesegenskaper avoid-large-mvps
Databasen för ekinnehåll som ligger till grund för AEM as a Cloud Service är inte avsedd att användas med ett stort antal flervärdesegenskaper (MVP). En tumregel är att hålla de privata leverantörerna under 1000. Den faktiska prestandan beror dock på många faktorer.
Varningar loggas som standard efter att ha överstigit 1000. De liknar följande.
org.apache.jackrabbit.oak.jcr.session.NodeImpl Large multi valued property [/path/to/property] detected (1029 values).
Stora MVP kan leda till fel på grund av att MongoDB-dokumentet överskrider 16 MB, vilket kan leda till fel som liknar följande.
Caused by: com.mongodb.MongoWriteException: Resulting document after update is larger than 16777216
Se Apache Oak-dokumentation för mer information.
Assets riktlinjer för utveckling och användningsfall use-cases-assets
Mer information om användningsfall, rekommendationer och referensmaterial för Assets as a Cloud Service finns i Utvecklarreferenser för Assets.