Como trabalhar com pacotes

Os pacotes permitem a importação e exportação de conteúdo do repositório. Por exemplo, você pode usar pacotes para instalar uma nova funcionalidade, transferir conteúdo entre instâncias e fazer backup do conteúdo do repositório.

Os pacotes podem ser acessados e/ou mantidos das seguintes páginas:

• Gerenciador de pacotes, que você usa para gerenciar os pacotes na instância de AEM local.

• Compartilhamento de pacotes, um servidor centralizado com pacotes disponíveis publicamente e privados para sua empresa. Os pacotes públicos podem conter hotfixes, nova funcionalidade, documentação, etc.

Você pode transferir pacotes entre o Gerenciador de pacotes, o Compartilhamento de pacotes e seu sistema de arquivos.

O que são pacotes?

Um pacote é um arquivo zip com conteúdo de repositório na forma de uma serialização de sistema de arquivos (chamada de serialização "vault"). Isso oferece uma representação fácil de usar e editar de arquivos e pastas.

Os pacotes incluem conteúdo, conteúdo de página e conteúdo relacionado ao projeto, selecionados por meio de filtros.

Um pacote também contém informações de metadados de cofre, incluindo as definições de filtro e informações de configuração de importação. Propriedades de conteúdo adicionais (que não são usadas para extração de pacotes) podem ser incluídas no pacote, como uma descrição, uma imagem visual ou um ícone; essas propriedades são para o consumidor do pacote de conteúdo e somente para fins informativos.

Você pode executar as seguintes ações em pacotes ou com pacotes:

• Criar novos pacotes; definição das configurações e filtros do pacote conforme necessário
• Visualizar o conteúdo do pacote (antes da criação)
• Criar pacotes
• Exibir informações do pacote
• Exibir o conteúdo do pacote (após a criação)
• Modificar a definição de pacotes existentes
• Reconstruir pacotes existentes
• Reembrulhar pacotes
• Baixe pacotes do AEM para seu sistema de arquivos
• Faça upload de pacotes do seu sistema de arquivos para a instância de AEM local
• Validar o conteúdo do pacote antes da instalação
• Executar uma instalação de simulação
• Instalar pacotes (AEM não instala pacotes automaticamente após o upload)
• Excluir pacotes
• Baixe pacotes, como hotfixes, da biblioteca de Compartilhamento de pacotes
• Fazer upload de pacotes para a seção interna da empresa da biblioteca de Compartilhamento de pacotes

Informações do pacote

Uma definição de pacote é composta por vários tipos de informações:

• Configurações do pacote
• Filtros do pacote
• Capturas de tela do pacote
• Ícones do pacote

Configurações do pacote

É possível editar várias Configurações do pacote para definir aspectos como a descrição do pacote, bugs relacionados, dependências e informações do provedor.

A caixa de diálogo Configurações do pacote está disponível por meio do botão Editar quando criar ou editar um pacote e fornece três guias para configuração. Depois que qualquer alteração for feita, clique em OK para salvá-las.

Filtros do pacote

Os filtros identificam os nós do repositório a serem incluídos no pacote. Uma Definição de Filtro especifica as seguintes informações:

• O Caminho raiz do conteúdo a ser incluído.
• ​​Regras que incluem ou excluem nós específicos abaixo do caminho raiz.

Os filtros podem incluir zero ou mais regras. Quando nenhuma regra é definida, o pacote contém todo o conteúdo abaixo do caminho raiz.

É possível definir uma ou mais definições de filtro para um pacote. Use mais de um filtro para incluir conteúdo de vários caminhos raiz.

A tabela a seguir descreve essas regras e fornece exemplos:

Os filtros de pacote são definidos com mais frequência ao criar o pacote pela primeira vez , mas também podem ser editados posteriormente (depois disso, o pacote deve ser recriado).

Capturas de tela do pacote

Você pode anexar capturas de tela ao seu pacote para fornecer uma representação visual da aparência do conteúdo; por exemplo, fornecendo capturas de tela de novas funcionalidades.

Ícones de Pacote

Você também pode anexar um ícone ao seu pacote para fornecer uma representação visual de referência rápida do que ele contém. Isso é mostrado na lista de pacotes e pode ajudar você a identificar facilmente o pacote ou a classe do pacote.

Como um pacote pode conter um ícone, as seguintes convenções são usadas para embalagens oficiais:

Pacote de hotfix oficial:

Pacote oficial AEM Instalação ou extensão:

Pacotes de recursos oficiais:

Gerenciador de pacotes

O Gerenciador de pacotes gerencia os pacotes na instalação local do AEM. Depois que você tiver atribuído as permissões necessárias, poderá usar o Gerenciador de pacotes para várias ações, incluindo a configuração, criação, download e instalação dos pacotes. Os principais elementos a serem configurados são:

• Configurações do pacote
• Filtros do pacote

Permissões necessárias para usar o Gerenciador de pacotes

Para conceder aos usuários o direito de criar, modificar, carregar e instalar pacotes, você deve conceder a eles as permissões apropriadas nos seguintes locais:

• /etc/packages (direitos totais excluindo exclusão)
• o nó que contém o conteúdo do pacote

Consulte Definindo permissões para obter instruções sobre como alterar permissões.

Criação de um novo pacote

Para criar uma nova definição de pacote:

1. Na tela de Boas-vindas AEM, clique em Pacotes (ou no console Ferramentas clique duas vezes em Pacotes).

2. Em seguida, selecione Gerenciador de Pacotes.

3. Clique em Criar pacote.

   OBSERVAÇÃO

   Se a instância tiver muitos pacotes, pode haver uma estrutura de pastas em vigor, para que você possa navegar até a pasta de destino necessária antes de criar o novo pacote.

4. Na caixa de diálogo:

   

   Insira:

   • Nome do grupo

     O nome do grupo de destino (ou pasta). Os grupos devem ser usados para ajudar a organizar seus pacotes.

     Uma pasta será criada para o grupo se ainda não existir. Se deixar o nome do grupo em branco, ele criará o pacote na lista de pacotes principais (Início > Pacotes).

   • Nome do pacote

     O nome do novo pacote. Selecione um nome descritivo para ajudá-lo (e outros) a identificar facilmente o conteúdo do pacote.

   • Versão

     Um campo textual para indicar uma versão. Isso será anexado ao nome do pacote para formar o nome do arquivo zip.
     Clique em OK para criar o pacote.

5. AEM lista o novo pacote na pasta de grupo apropriada.

   

   Clique no ícone ou no nome do pacote para abrir.

   

   OBSERVAÇÃO

   Você pode retornar a essa página em um estágio posterior, se necessário.

6. Clique em Editar para editar as configurações de pacote.

   Aqui, você pode adicionar informações e/ou definir determinadas configurações; por exemplo, eles incluem uma descrição, o ícone, bugs relacionados e adicionar detalhes do provedor.

   Clique em OK depois de concluir a edição das configurações.

7. Adicione Capturas de tela ao pacote, conforme necessário. Uma instância está disponível quando o pacote é criado, adicione mais, se necessário, usando Captura de tela do pacote do sidekick.

   Adicione a imagem real clicando duas vezes no componente de imagem na área Capturas de tela, adicionando uma imagem e clicando em OK.

8. Defina os Filtros de Pacote arrastando instâncias de Definição de Filtro do sidekick e clicando duas vezes para abrir para edição:

   

   Especifique:

   • Caminho raizO conteúdo a ser embalado;
     essa pode ser a raiz de uma subárvore.

   • ​
     RegrasAs regras são opcionais; para definições de pacote simples, não é necessário especificar regras de inclusão ou exclusão.

     Se necessário, você pode definir Include ou Exclude rules para definir exatamente o conteúdo do pacote.

     Adicione regras usando o símbolo +, como alternativa, remova regras usando o símbolo -. As regras são aplicadas de acordo com sua ordem, de forma que sejam posicionadas conforme necessário usando os botões Up e Down.
     Em seguida, clique em OK para salvar o filtro.

   OBSERVAÇÃO

   Você pode usar quantas definições de filtro forem necessárias, embora seja necessário tomar cuidado para garantir que elas não entrem em conflito. Use Preview para confirmar o conteúdo do pacote.

9. Para confirmar o que o pacote manterá, você poderá usar Preview. Isso executa uma execução seca do processo de criação e lista tudo que será adicionado ao pacote quando ele for realmente criado.

10. Agora você pode Criar seu pacote.

    OBSERVAÇÃO

    Não é obrigatório construir o pacote neste momento, pode ser feito posteriormente.

Criar um pacote

Geralmente, um pacote é criado ao mesmo tempo que você cria a definição de pacote, mas você pode retornar posteriormente para criar ou reconstruir o pacote. Isso pode ser útil se o conteúdo no repositório tiver sido alterado.

1. Abra a definição de pacote em Gerenciador de Pacotes (clique no ícone ou nome do pacote).

2. Clique em Criar. Uma caixa de diálogo solicita a confirmação de que você deseja criar o pacote.

   OBSERVAÇÃO

   Isso é de especial importância quando você está recriando um pacote, pois o conteúdo do pacote será substituído.

3. Clique em OK. AEM criará o pacote, listando todo o conteúdo adicionado ao pacote da maneira que ele fizer. Ao concluir o AEM, você exibe uma confirmação de que o pacote foi criado e (ao fechar a caixa de diálogo) atualiza as informações da lista de pacotes.

Reembrulhar um pacote

Depois que um pacote é criado, ele pode ser reembutido, se necessário.

Rewrapping altera as informações do pacote - sem alterar o conteúdo do pacote. As informações do pacote são a miniatura, a descrição etc., em outras palavras, tudo o que você pode editar com a caixa de diálogo Configurações do pacote (para abrir, clique em Editar).

Um caso de uso importante para refazer é ao preparar um pacote para o compartilhamento de pacote. Por exemplo, você pode ter um pacote existente e decidir compartilhá-lo com outras pessoas. Para isso, adicione uma miniatura e uma descrição. Em vez de recriar o pacote inteiro com toda a funcionalidade (o que pode levar algum tempo e correr o risco de o pacote não ser mais idêntico ao original), você pode refazer o encapsulamento e adicionar a miniatura e a descrição.

1. Abra a definição de pacote em Gerenciador de Pacotes (clique no ícone ou nome do pacote).

2. Clique em Editar e atualize as Configurações do Pacote conforme necessário. Clique em OK para salvar.

3. Clique em Reenvolver, uma caixa de diálogo pedirá confirmação.

Exibindo e editando informações do pacote

Para exibir ou editar informações sobre uma definição de pacote:

1. No Gerenciador de pacotes, navegue até o pacote que deseja visualizar.

2. Clique no ícone de pacote do pacote que deseja visualizar. Isso abrirá a página do pacote listando informações sobre a definição do pacote:

   

   OBSERVAÇÃO

   Também é possível editar e executar determinadas ações no pacote nessa página.

   Os botões disponíveis dependerão se o pacote já foi criado ou não.

3. Se o pacote já tiver sido criado, clique em Contents, uma janela será aberta e listará todo o conteúdo do pacote:

Visualização do conteúdo do pacote e teste da instalação

Após a criação de um pacote, você pode exibir o conteúdo:

1. No Gerenciador de pacotes, navegue até o pacote que deseja visualizar.

2. Clique no ícone de pacote do pacote que deseja visualizar. Isso abrirá a página do pacote listando informações sobre a definição do pacote.

3. Para exibir o conteúdo, clique em Contents, uma janela será aberta e listará todo o conteúdo do pacote:

   

4. Para executar uma simulação de instalação, clique em Testar Instalação. Após confirmar a ação, uma janela será aberta e listará os resultados como se a instalação tivesse sido executada:

   

Fazendo download de pacotes no seu sistema de arquivos

Esta seção descreve como baixar um pacote do AEM para seu sistema de arquivos usando o Gerenciador de Pacotes.

1. Na tela de Boas-vindas AEM, clique em Pacotes e selecione Gerenciador de Pacotes.

2. Navegue até o pacote que deseja baixar.

   

3. Clique no link formado pelo nome do arquivo zip (sublinhado) para o pacote que deseja baixar; por exemplo export-for-offline.zip.

   AEM o download do pacote para seu computador (usando uma caixa de diálogo padrão de download do navegador).

Fazer upload de pacotes do seu sistema de arquivos

Um upload de pacote permite fazer upload de um pacote de seu sistema de arquivos para o Gerenciador de pacotes de AEM.

Para fazer upload de um pacote:

1. Navegue até o Gerenciador de Pacotes. Em seguida, na pasta do grupo na qual deseja que o pacote seja carregado.

   

2. Clique em Fazer upload do pacote.

   

   • Arquivo

     Você pode digitar o nome do arquivo diretamente ou usar o Procurar… para selecionar o pacote necessário do sistema de arquivos local (após a seleção, clique em OK).

   • Forçar atualização

     Se um pacote com esse nome já existir, você poderá clicar nele para forçar o upload (e substituir o pacote existente).
     Clique em OK para que o novo pacote seja carregado e listado na lista Gerenciador de pacotes.

   OBSERVAÇÃO

   Para disponibilizar o conteúdo para o AEM, certifique-se de instalar o pacote.

Validando pacotes

Antes de instalar um pacote, convém verificar seu conteúdo. Como os pacotes podem modificar arquivos sobrepostos em /apps e/ou adicionar, modificar e remover ACLs, geralmente é útil validar essas alterações antes de instalar.

Opções de validação

O mecanismo de validação pode verificar as seguintes características do pacote:

• Importações de pacotes OSGi
• Sobreposições
• ACLs

Essas opções são detalhadas abaixo.

• Validar importações do pacote OSGi

  O que está marcado

  Essa validação inspeciona o pacote de todos os arquivos JAR (pacotes OSGi), extrai seus manifest.xml (que contém as dependências com versão das quais o pacote OSGi depende) e verifica as exportações da instância AEM mencionadas dependências com as versões corretas.

  Como é reportado

  Quaisquer dependências com versão que não possam ser atendidas pela instância de AEM são listadas no Log de Atividades do Gerenciador de Pacotes.

  Estados de erro

  Se as dependências não forem atendidas, os pacotes OSGi no pacote com essas dependências não serão iniciados. Isso resulta em uma implantação de aplicativo interrompida, pois qualquer coisa que dependa do pacote OSGi não iniciado, por sua vez, não funcionará corretamente.

  Resolução de Erro

  Para resolver erros devido a pacotes OSGi insatisfeitos, a versão de dependência no pacote com importações insatisfeitas precisa ser ajustada.

• Validar sobreposições

  O que está marcado

  Essa validação determina se o pacote que está sendo instalado contém um arquivo que já está sobreposto na instância de destino AEM.

  Por exemplo, considerando uma sobreposição existente em /apps/sling/servlet/errorhandler/404.jsp, um pacote que contém /libs/sling/servlet/errorhandler/404.jsp, de modo que alterará o arquivo existente em /libs/sling/servlet/errorhandler/404.jsp.

  Como é reportado

  Essas sobreposições são descritas no Log de atividades do Gerenciador de pacotes.

  Estados de erro

  Um estado de erro significa que o pacote está tentando implantar um arquivo que já está sobreposto, portanto, as alterações no pacote serão sobrepostas (e, portanto, "ocultas") pela sobreposição e não terão efeito.

  Resolução de Erro

  Para resolver esse problema, o mantenedor do arquivo de sobreposição em /apps deve revisar as alterações no arquivo sobreposto em /libs, incorporar as alterações conforme necessário na sobreposição ( /apps) e reimplantar o arquivo sobreposto.

  OBSERVAÇÃO

  Observe que o mecanismo de validação não tem como reconciliar se o conteúdo sobreposto foi incorporado corretamente no arquivo de sobreposição. Por conseguinte, esta validação continuará a apresentar relatórios sobre conflitos mesmo depois de terem sido efetuadas as alterações necessárias.

• Validar ACLs

  O que está marcado

  Essa validação verifica quais permissões estão sendo adicionadas, como serão tratadas (mesclar/substituir) e se as permissões atuais serão afetadas.

  Como é reportado

  As permissões são descritas no Log de atividades do Gerenciador de pacotes.

  Estados de erro

  Não é possível fornecer erros explícitos. A validação simplesmente indica se qualquer nova permissão ACL será adicionada ou afetada pela instalação do pacote.

  Resolução de Erro

  Usando as informações fornecidas pela validação, os nós afetados podem ser revisados no CRXDE e as ACLs podem estar ajustando no pacote conforme necessário.

  CUIDADO

  Como prática recomendada, é recomendável que os pacotes não afetem as ACLs fornecidas AEM, pois isso pode resultar em comportamento inesperado do produto.

Executando Validação

A validação dos pacotes pode ser feita de duas maneiras diferentes:

• Por meio da interface do usuário do Gerenciador de pacotes
• Por meio de solicitação HTTP POST, como com cURL

Validação do pacote por meio do Gerenciador de pacotes

1. Abra o Gerenciador de Pacotes em https://<server>:<port>/crx/packmgr

2. Selecione o pacote na lista e selecione Mais lista suspensa no cabeçalho e Validar no menu suspenso.

   OBSERVAÇÃO

   Isso deve ser feito após o upload do pacote de conteúdo, mas antes da instalação do pacote.

3. Na caixa de diálogo modal que aparece, use as caixas de seleção para selecionar os tipos de validação e iniciar a validação clicando em Validar. Como alternativa, clique em Cancelar.

4. As validações escolhidas são executadas. Os resultados são exibidos no registro de atividades do Gerenciador de pacotes.

Validação de pacote por solicitação POST HTTP

A solicitação POST assume o seguinte formulário.

https://<host>:<port>/crx/packmgr/service.jsp?cmd=validate&type=osgiPackageImports,overlays,acls

Veja a seguir um exemplo de uso de cURL para executar uma validação de pacote.

1. Se estiver usando cURL, execute uma instrução semelhante ao seguinte:

   curl -v -X POST --user admin:admin -F file=@/Users/SomeGuy/Desktop/core.wcm.components.all-1.1.0.zip 'http://localhost:4502/crx/packmgr/service.jsp?cmd=validate&type=osgiPackageImports,overlays,acls'
   

2. A validação solicitada é executada e a resposta é enviada de volta como um objeto JSON.

Instalação de pacotes

Após fazer upload de um pacote, é necessário instalar o conteúdo. Para ter o conteúdo do pacote instalado e funcional, ele precisa ser:

• carregado no AEM (ou carregado do sistema de arquivos ou baixado do compartilhamento de pacotes)

• instalados

1. No Gerenciador de pacotes, navegue até o pacote que deseja instalar.

   Um botão Install é exibido na lateral de Pacotes que ainda não foram instalados.

   OBSERVAÇÃO

   Como alternativa, abra o pacote clicando no ícone para acessar o botão Install.

2. Clique em Instalar para iniciar a instalação. Uma caixa de diálogo solicitará a confirmação e listará todas as alterações feitas. Quando terminar, clique em Fechar na caixa de diálogo.

   A palavra Installed aparece ao lado do pacote depois de ele ter sido instalado.

Upload e instalação baseados no sistema de arquivos

Há uma maneira alternativa de carregar e instalar pacotes na sua instância. No seu sistema de arquivos, você tem uma pasta crx-quicksart junto com seu jar e license.properties arquivo. Você precisa criar uma pasta chamada install em crx-quickstart. Você terá algo assim: <aem_home>/crx-quickstart/install

Nesta instalação, pasta , é possível adicionar diretamente os pacotes. Eles serão carregados e instalados automaticamente na sua instância. Quando terminar, você poderá ver os pacotes no Gerenciador de pacotes.

Se a instância estiver em execução, adicionar um pacote à pasta install iniciará diretamente o upload e a instalação na instância. Se a instância não estiver em execução, os pacotes colocados na pasta install serão instalados na inicialização, na ordem alfabética.

Desinstalando pacotes

AEM permite desinstalar pacotes. Essa ação reverte o conteúdo do repositório que é afetado ao instantâneo feito imediatamente antes da instalação do pacote.

1. No Gerenciador de pacotes, navegue até o pacote que você deseja desinstalar.
2. Clique no ícone de pacote do pacote que deseja desinstalar.
3. Clique em Uninstall para remover o conteúdo deste pacote do repositório. Uma caixa de diálogo solicitará a confirmação e listará todas as alterações feitas. Quando terminar, clique em Fechar na caixa de diálogo.

Excluindo pacotes

Para excluir um pacote da(s) lista(ões) do Gerenciador de Pacotes:

1. No console Tools, expanda a pasta Packages para mostrar seu pacote no painel direito.

2. Clique no pacote que deseja excluir para realçá-lo e, em seguida:

   • Clique em Excluir no menu da barra de ferramentas.
   • Clique com o botão direito do mouse e selecione Delete.

   

3. AEM solicita a confirmação de que você deseja excluir o pacote. Clique em OK para confirmar a exclusão.

Replicando pacotes

Replicar o conteúdo de um pacote para instalá-lo na instância de publicação:

1. No Gerenciador de Pacotes, navegue até o pacote que deseja replicar.

2. Clique no ícone ou no nome do pacote que deseja replicar para expandi-lo.

3. No menu suspenso Mais na barra de ferramentas, selecione Replicar.

Compartilhamento de pacotes

O Compartilhamento de pacotes foi um servidor centralizado disponibilizado publicamente para compartilhar os Pacotes de conteúdo.

Ele foi substituído por Distribuição de software.

Distribuição de software

A Distribuição de software é a nova interface de usuário criada para simplificar a pesquisa e o download de pacotes AEM.

Para obter mais informações, consulte a Documentação de Distribuição de Software.