Diretrizes de desenvolvimento do AEM as a Cloud Service aem-as-a-cloud-service-development-guidelines

Este documento apresenta diretrizes para desenvolver o no AEM as a Cloud Service e sobre maneiras importantes de diferenciar o AEM nas instalações e o AEM no AMS.

O Código Deve Reconhecer Cluster cluster-aware

O código em execução no AEM as a Cloud Service deve reconhecer o fato de que ele está sempre em execução em um cluster. Isso significa que sempre há mais de uma instância em execução. O código deve ser resiliente, especialmente porque uma instância pode ser interrompida a qualquer momento.

Durante a atualização do AEM as a Cloud Service, há instâncias com código novo e antigo em execução em paralelo. Portanto, o código antigo não deve quebrar com o conteúdo criado pelo novo código e o novo código deve ser capaz de lidar com o conteúdo antigo.

Se for necessário identificar o principal no cluster, a API de descoberta do Apache Sling poderá ser usada para detectá-lo.

Estado na memória state-in-memory

O estado não deve ser mantido na memória, mas mantido no repositório. Caso contrário, esse estado poderá ser perdido se uma instância for interrompida.

Estado no sistema de arquivos state-on-the-filesystem

Não use o sistema de arquivos da instância no AEM as a Cloud Service. O disco é efêmero e é descartado quando as instâncias são recicladas. O uso limitado do sistema de arquivos para armazenamento temporário relacionado ao processamento de solicitações únicas é possível, mas não deve ser usado para arquivos enormes. Isso ocorre porque pode ter um impacto negativo na cota de uso do recurso e gerar limitações de disco.

Por exemplo, quando o uso do sistema de arquivos não for aceito, a camada da Publish deve garantir que todos os dados que devem ser mantidos sejam enviados para um serviço externo para armazenamento de longo prazo.

Observação observation

Semelhante, com tudo o que está acontecendo de forma assíncrona, como a ação em eventos de observação, não é possível garantir que seja executado localmente e, portanto, deve ser usado com cuidado. Isso é verdadeiro para eventos JCR e eventos de recursos Sling. No momento em que uma alteração estiver ocorrendo, a instância poderá ser desativada e substituída por outra instância. Outras instâncias na topologia que estão ativas nesse momento podem reagir a esse evento. Nesse caso, no entanto, não será um evento local e pode até não haver líder ativo no caso de uma eleição de líder em andamento quando o evento for emitido.

Tarefas de segundo plano e tarefas de longa duração background-tasks-and-long-running-jobs

O código executado como tarefas em segundo plano deve supor que a instância em que está sendo executada pode ser desativada a qualquer momento. Portanto, o código deve ser resiliente e, o mais importante, retomável. Isso significa que, se o código for executado novamente, ele não deverá começar do início novamente, mas sim próximo de onde parou. Embora esse não seja um requisito novo para esse tipo de código, no AEM as a Cloud Service é mais provável que uma instância seja desativada.

Para minimizar o problema, se possível, a execução de trabalhos de longa duração deve ser evitada, e eles devem ser retomáveis no mínimo. Para executar esses trabalhos, use o Sling Jobs, que têm uma garantia de pelo menos uma vez e, portanto, se forem interrompidos, serão reexecutados o mais rápido possível. Mas elas provavelmente não devem recomeçar do início. Para agendar esses trabalhos, é melhor usar o agendador Trabalhos do Sling, pois isso garante novamente a execução de pelo menos uma vez.

Não use o Sling Commons Scheduler para agendamento, pois a execução não pode ser garantida. É mais provável que ela esteja programada.

Da mesma forma, com tudo o que está acontecendo de forma assíncrona, como a atuação em eventos de observação (ou seja, eventos JCR ou eventos de recursos Sling), não é garantido que seja executado e, portanto, deve ser usado com cuidado. Isso já é verdadeiro para implantações de AEM no presente.

Conexões HTTP de Saída outgoing-http-connections

É altamente recomendável que qualquer conexão HTTP de saída defina tempos limite de conexão e leitura razoáveis; os valores sugeridos são 1 segundo para o tempo limite da conexão e 5 segundos para o tempo limite de leitura. Os números exatos devem ser determinados com base no desempenho do sistema de back-end que lida com essas solicitações.

Para o código que não aplica esses tempos limite, as instâncias de AEM em execução no AEM as a Cloud Service aplicarão um tempo limite global. Esses valores de tempo limite são de 10 segundos para chamadas de conexão e 60 segundos para chamadas de leitura para conexões.

O Adobe recomenda o uso da biblioteca Apache HttpComponents Client 4.x fornecida para fazer conexões HTTP.

Alternativas que são conhecidas por funcionar, mas podem exigir que você forneça a dependência:

Além de fornecer tempos limite, também deve ser implementado um tratamento adequado desses tempos limite e códigos de status HTTP inesperados.

Lidar com limites de taxa de solicitação rate-limit-handling

Quando a taxa de solicitações recebidas para o AEM excede os níveis íntegros, o AEM responde a novas solicitações com o código de erro HTTP 429. Os aplicativos que fazem chamadas programáticas para AEM podem considerar a codificação defensivamente, tentando novamente após alguns segundos com uma estratégia de retirada exponencial. Antes de meados de agosto de 2023, o AEM respondia à mesma condição com o código de erro HTTP 503.

Nenhuma personalização da interface clássica no-classic-ui-customizations

O AEM as a Cloud Service só oferece suporte à interface para toque para código de cliente de terceiros. A interface clássica não está disponível para personalização.

Não há binários nativos ou bibliotecas nativas avoid-native-binaries

Os binários e bibliotecas nativos não devem ser implantados ou instalados em ambientes de nuvem.

Além disso, o código não deve tentar baixar binários nativos ou extensões java nativas (por exemplo, JNI) no tempo de execução.

Nenhum binário de transmissão por meio do AEM as a Cloud Service no-streaming-binaries

Os binários devem ser acessados por meio da CDN, que fornecerá binários fora dos serviços principais de AEM.

Por exemplo, não use asset.getOriginal().getStream(), que dispara o download de um binário no disco efêmero do serviço AEM.

Nenhum agente de replicação reversa no-reverse-replication-agents

A replicação reversa do Publish para o Author não é compatível com o AEM as a Cloud Service. Se essa estratégia for necessária, você poderá usar um armazenamento de persistência externo que é compartilhado entre o farm de instâncias do Publish e possivelmente o cluster Author.

Talvez seja necessário transferir os agentes de replicação direta forward-replication-agents

O conteúdo é replicado do Author para o Publish por meio de um mecanismo pub-sub. Os agentes de replicação personalizados não são compatíveis.

Sem sobrecarga nos ambientes de desenvolvimento overloading-dev-envs

Os ambientes de produção são dimensionados mais alto para garantir uma operação estável, enquanto os ambientes de preparo são dimensionados como ambientes de produção para garantir testes realistas em condições de produção.

Os ambientes de desenvolvimento e os ambientes de desenvolvimento rápido devem se limitar ao desenvolvimento, à análise de erros e aos testes funcionais, e não foram projetados para processar altas cargas de trabalho nem grandes quantidades de conteúdo.

Por exemplo, alterar uma definição de índice em um grande repositório de conteúdo em um ambiente de desenvolvimento pode resultar na reindexação, resultando em muito processamento. Os testes que exigem conteúdo substancial devem ser executados em ambientes de preparo.

Monitoramento e depuração monitoring-and-debugging

Logs logs

Para desenvolvimento local, entradas de logs são gravadas em arquivos locais na pasta /crx-quickstart/logs.

Em ambientes na nuvem, os desenvolvedores podem baixar logs por meio do Cloud Manager ou usar uma ferramenta de linha de comando para rastrear os logs.

Definindo o Nível de Log

Para alterar os níveis de log para ambientes em nuvem, a configuração OSGI do Sling Logging deve ser modificada, seguida de uma reimplantação completa. Como isso não é instantâneo, tenha cuidado ao ativar registros detalhados em ambientes de produção que recebem muito tráfego. No futuro, é possível que haja mecanismos para alterar mais rapidamente o nível de log.

Ativando o Nível de Log DEBUG

O nível de log padrão é INFO, ou seja, as mensagens DEBUG não são registradas. Para ativar o nível de log DEBUG, atualize a propriedade a seguir para o modo de depuração.

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

Por exemplo, defina /apps/<example>/config/org.apache.sling.commons.log.LogManager.factory.config~<example>.cfg.json com o seguinte valor.

{
   "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"
}

Não deixe o log no nível de log DEBUG por mais tempo do que o necessário, pois isso gera muitas entradas.

É possível definir níveis de log discretos para os diferentes ambientes AEM usando o direcionamento de configuração OSGi baseada em modo de execução, se for desejável sempre registrar em DEBUG durante o desenvolvimento. Por exemplo:

Uma linha no arquivo de depuração geralmente começa com DEBUG e, em seguida, fornece o nível de log, a ação do instalador e a mensagem de log. Por exemplo:

DEBUG 3 WebApp Panel: WebApp successfully deployed

Os níveis de log são os seguintes:

Despejos de encadeamento thread-dumps

Os despejos de thread em ambientes na nuvem são coletados de forma contínua, mas não podem ser baixados de forma automatizada no momento. Enquanto isso, entre em contato com o suporte do AEM se os despejos de thread forem necessários para depurar um problema, especificando a janela de tempo exata.

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

Desenvolvimento local local-development

Para desenvolvimento local, os desenvolvedores têm acesso total ao CRXDE Lite (/crx/de) e ao Console da Web AEM (/system/console).

No desenvolvimento local (usando o SDK), /apps e /libs podem ser gravados diretamente, o que é diferente dos ambientes em nuvem, onde essas pastas de nível superior são imutáveis.

Ferramentas de desenvolvimento do AEM as a Cloud Service aem-as-a-cloud-service-development-tools

Os clientes podem acessar o CRXDE lite no ambiente de desenvolvimento do nível do autor, mas não no ambiente de preparo ou produção. O repositório imutável (/libs, /apps) não pode ser gravado no tempo de execução, portanto, tentar fazer isso resultará em erros.

Em vez disso, o Navegador do repositório pode ser iniciado no AEM as a Cloud Service Developer Console, fornecendo uma visualização somente leitura no repositório para todos os ambientes nos níveis de criação, publicação e visualização. Para obter mais informações, consulte o Navegador do Repositório.

Um conjunto de ferramentas para depurar ambientes de desenvolvedor do AEM as a Cloud Service está disponível no AEM as a Cloud Service Developer Console para ambientes de RDE, desenvolvimento, preparo e produção. O URL pode ser determinado ajustando os URLs de serviço do Autor ou do Publish da seguinte maneira:

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

Como atalho, o seguinte comando da CLI do Cloud Manager pode ser usado para iniciar o AEM as a Cloud Service Developer Console com base em um parâmetro de ambiente descrito abaixo:

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

Consulte as Informações da versão para obter mais informações.

Os desenvolvedores podem gerar informações de status e resolver vários recursos.

Como ilustrado abaixo, as informações de status disponíveis incluem o estado dos pacotes, componentes, configurações OSGI, índices Oak, serviços OSGI e trabalhos Sling.

Como ilustrado abaixo, os desenvolvedores podem resolver as dependências de pacote e os servlets:

Também útil para depuração, o AEM as a Cloud Service Developer Console tem um link para a ferramenta Explicar consulta:

Para programas de produção, o acesso ao AEM as a Cloud Service Developer Console é definido pela "Função do desenvolvedor - Cloud Manager" no Adobe Admin Console, enquanto para programas de sandbox, o AEM as a Cloud Service Developer Console está disponível para qualquer usuário com um perfil de produto que dê acesso ao AEM as a Cloud Service. Para todos os programas, "Cloud Manager - Função do desenvolvedor" é necessário para despejos de status, e o navegador do repositório e os usuários também devem ser definidos no Perfil de produto Usuários do AEM ou Administradores do AEM nos serviços de criação e publicação para exibir dados de ambos os serviços. Para obter mais informações sobre como configurar permissões de usuário, consulte a Documentação do Cloud Manager.

Monitoramento de desempenho performance-monitoring

O Adobe monitora o desempenho do aplicativo e toma medidas para lidar com a deterioração observada. No momento, as métricas de aplicação não podem ser observadas.

Envio de email sending-email

As seções abaixo descrevem como solicitar, configurar e enviar emails.

Ativação de email de saída enabling-outbound-email

Por padrão, as portas usadas para enviar email são desativadas. Para ativar uma porta, configure a rede avançada, certificando-se de definir para cada ambiente necessário as regras de encaminhamento de porta do ponto de extremidade PUT /program/<program_id>/environment/<environment_id>/advancedNetworking, que mapeia a porta pretendida (por exemplo, 465 ou 587) para uma porta proxy.

É recomendável configurar a rede avançada com um parâmetro kind definido como flexiblePortEgress, já que o Adobe pode otimizar o desempenho do tráfego de saída de porta flexível. Se um endereço IP de saída exclusivo for necessário, escolha um parâmetro kind de dedicatedEgressIp. Se você já tiver configurado a VPN por outros motivos, também poderá usar o endereço IP exclusivo fornecido por essa variação avançada de rede.

Você deve enviar e-mails por meio de um servidor de e-mail em vez de diretamente para clientes de e-mail. Caso contrário, os emails poderão ser bloqueados.

Envio de emails sending-emails

O Serviço OSGI do Day CQ Mail Service deve ser usado e os emails devem ser enviados para o servidor de email indicado na solicitação de suporte, em vez de diretamente para os destinatários.

Configuração email-configuration

Emails no AEM devem ser enviados usando o Serviço OSGi do Day CQ Mail Service.

Consulte a documentação do AEM 6.5 para obter detalhes sobre como definir configurações de email. Para o AEM as a Cloud Service, observe os seguintes ajustes necessários para o serviço com.day.cq.mailer.DefaultMailService OSGI:

A porta do servidor SMTP deve ser definida como o valor portDest definido no parâmetro portForwards usado na chamada de API ao configurar a rede avançada, e o valor portOrig deve ser um valor significativo dentro do intervalo necessário de 30000 a 30999. Por exemplo, se a porta do servidor SMTP for 465, a porta 30465 deverá ser usada como o valor portOrig.

Nesse caso, e supondo que o SSL precise ser habilitado, na configuração do serviço OSGI do Day CQ Mail Service:

Como alternativa, se a porta de destino for 587, um valor portOrig de 30587 deverá ser usado. E supondo que o SSL deve ser desativado, a configuração do serviço OSGI do Day CQ Mail Service:

A propriedade smtp.starttls será automaticamente definida pelo AEM as a Cloud Service em tempo de execução como um valor apropriado. Assim, se smtp.ssl estiver definido como verdadeiro, smtp.startls será ignorado. Se smtp.ssl estiver definido como falso, smtp.starttls será definido como verdadeiro. Isso ocorre independentemente dos valores smtp.starttls definidos na sua configuração OSGI.

O Serviço de e-mail pode, opcionalmente, ser configurado com suporte para OAuth2. Para obter mais informações, consulte Suporte do OAuth2 para o Serviço de Email.

Configuração de email herdada legacy-email-configuration

Antes da versão 2021.9.0, o email era configurado por meio de uma solicitação de suporte ao cliente. Observe os seguintes ajustes necessários para o serviço com.day.cq.mailer.DefaultMailService OSGI:

O AEM as a Cloud Service exige que o email seja enviado pela porta 465. Se um servidor de e-mail não suportar a porta 465, a porta 587 poderá ser usada, desde que a opção TLS esteja habilitada.

Se a porta 465 tiver sido solicitada:

e se a porta 587 tiver sido solicitada:

A propriedade smtp.starttls será automaticamente definida pelo AEM as a Cloud Service em tempo de execução como um valor apropriado. Assim, se smtp.ssl estiver definido como verdadeiro, smtp.startls será ignorado. Se smtp.ssl estiver definido como falso, smtp.starttls será definido como verdadeiro. Isso ocorre independentemente dos valores smtp.starttls definidos na sua configuração OSGI.

O host do servidor SMTP deve ser definido como o do seu servidor de e-mail.

Evite propriedades grandes de vários valores avoid-large-mvps

O repositório de conteúdo do Oak subjacente ao AEM as a Cloud Service não deve ser usado com um número excessivo de propriedades de vários valores (MVPs). Uma regra geral é manter os MVPs abaixo de 1000. No entanto, o desempenho real depende de muitos fatores.

Os avisos são registrados por padrão depois de exceder 1000. Elas são semelhantes às seguintes.

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

MVPs grandes podem levar a erros porque o documento MongoDB excede 16 MB, resultando em erros semelhantes aos seguintes.

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

Consulte a documentação do Apache Oak para obter mais detalhes.

Diretrizes de desenvolvimento e casos de uso do Assets use-cases-assets

Para saber mais sobre os casos de uso de desenvolvimento, as recomendações e os materiais de referência do Assets as a Cloud Service, consulte Referências do desenvolvedor para Assets.