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:

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.

NOTE
Om du vill utföra konfigurationsändringarna som anges nedan skapar du dem i en lokal utvecklingsmiljö och skickar dem sedan till en AEM as a Cloud Service instans. Mer information om hur du gör detta finns i Distribuera till AEM as a Cloud Service.

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:

Miljö
OSGi-konfigurationsplats via körningsläge
org.apache.sling.commons.log.level egenskapsvärde
Utveckling
/apps/example/config/org.apache.sling.Commons.log.LogManager.factory.config~example.cfg.json
FELSÖKNING
Scen
/apps/example/config.stage/org.apache.sling.Commons.log.LogManager.factory.config~example.cfg.json
VARNING
Produktion
/apps/example/config.prod/org.apache.sling.Commons.log.LogManager.factory.config~example.cfg.json
FEL

En 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:

0
Allvarligt fel
Åtgärden misslyckades och installationsprogrammet kan inte fortsätta.
1
Fel
Åtgärden misslyckades. Installationen fortsätter, men en del av CRX installerades inte korrekt och kommer inte att fungera.
2
Varning
Åtgärden har slutförts men problem uppstod. CRX fungerar eventuellt inte korrekt.
3
Information
Åtgärden har slutförts.

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

NOTE
Den AEM as a Cloud Service utvecklarkonsolen ska inte blandas ihop med liknande namn Adobe Developer Console.

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.

Dev Console 1

Som framgår nedan kan utvecklare lösa paketberoenden och -servrar:

Dev Console 2

Dev Console 3

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:

Dev Console 4

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.

NOTE
E-posttjänsten kan konfigureras med OAuth2-stöd. Mer information finns i OAuth2-stöd för e-posttjänsten.

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 till 30465
  • Ange smtp.ssl till true

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 till 30587
  • Ange smtp.ssl till false

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 till 465
  • set smtp.ssl till true

och om port 587 har begärts:

  • set smtp.port till 587
  • set smtp.ssl till false

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.

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab