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 nas seguintes páginas:

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

• Distribuição de software, um servidor centralizado que contém pacotes disponíveis publicamente e os particulares para sua empresa. Os pacotes públicos podem conter hotfixes, nova funcionalidade, documentação etc.

Você pode transferir pacotes entre o Gerenciador de pacotes, a Distribuição de software e seu sistema de arquivos.

O que são os pacotes?

Um pacote é um arquivo zip que contém o conteúdo do repositório na forma de uma serialização do sistema de arquivos (chamada de serialização "vault"). Isso proporciona 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, selecionado usando filtros.

Um pacote também contém informações meta do cofre, incluindo as definições de filtro e as informações de configuração de importação. Propriedades de conteúdo adicionais (que não são usadas para a extração do pacote) 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 apenas para fins informativos.

É possível executar as seguintes ações em ou com pacotes:

• Criar novos pacotes; definição das configurações e filtros do pacote, conforme necessário
• Conteúdo do pacote de pré-visualização (antes da compilação)
• Criar pacotes
• Informações do pacote de visualização
• Conteúdo do pacote de visualização (após a criação)
• Modificar a definição de pacotes existentes
• Reconstruir pacotes existentes
• Reembrulhar pacotes
• Baixar pacotes do AEM para o seu sistema de arquivos
• Faça upload de pacotes do seu sistema de arquivos para a instância AEM local
• Validar o conteúdo do pacote antes da instalação
• Execute uma instalação em funcionamento
• Instalar pacotes (AEM não instala automaticamente os pacotes após o upload)
• Excluir pacotes
• Baixe os pacotes, como hotfixes, da biblioteca de distribuição de software
• Carregar pacotes na seção interna da empresa da biblioteca de distribuição de software

Informações do pacote

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

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

Configurações do pacote

Você pode 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 através do botão Editar quando criar ou editar um pacote e fornece três guias para configuração. Depois de fazer qualquer alteração, clique em OK para salvá-las.

Texto	Descrição
Nome	O nome do pacote.
Grupo	O nome do grupo ao qual o pacote será adicionado para organizar os pacotes. Digite o nome de um novo grupo ou selecione um grupo existente.
Versão	Texto a ser usado para a versão personalizada.
Descrição	Uma breve descrição do pacote. A marcação HTML pode ser usada para formatação.
Miniatura	O ícone que aparece com a lista de pacotes. Clique em Procurar para selecionar um arquivo local.

Texto	Descrição	Formato/Exemplo
Nome	O nome do provedor.	Geometrixx AEM
URL	URL do provedor.	https://www.aem-geometrixx.com
Link	Link específico do pacote para uma página do provedor.	https://www.aem-geometrixx.com/mypackage.html
Exige	Administrador: Selecione quando o pacote só pode ser instalado por uma conta com privilégios de administrador. Reiniciar: Selecione quando o servidor precisa ser reiniciado após a instalação do pacote.
Reparação de AC	Especifique como as informações de controle de acesso definidas no pacote são tratadas quando o pacote é importado: Ignorar Substituir Mesclar Limpar MergePreserve O valor padrão é Ignorar.	Ignorar - preservar ACLs no repositório Substituir - substituir ACLs no repositório Mesclar - mesclar ambos os conjuntos de ACLs Limpar - limpar ACLs MergePreserve - mescla o controle de acesso no conteúdo com o fornecido com o pacote adicionando as entradas de controle de acesso de principais não presentes no conteúdo

Texto	Descrição	Formato/Exemplo
Testado com	O nome e a versão do produto para os quais este pacote está direcionado ou é compatível.	AEM 6
Erros/problemas corrigidos	Um campo de texto que permite a lista de detalhes de erros corrigidos com este pacote. Lista cada bug em uma linha separada.	resumo bug-nr
Depende de	Lista informações de dependência que precisam ser respeitadas sempre que outros pacotes forem necessários para permitir que o pacote atual seja executado conforme esperado. Esse campo é importante ao usar hotfixes.	groupId:name:version
Substitui	Uma lista de pacotes obsoletos que este pacote substitui. Antes de instalar, verifique se este pacote inclui todo o conteúdo necessário dos pacotes obsoletos para que nenhum conteúdo seja substituído.	groupId:name:version

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.

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:

Tipo de regra	Descrição	Exemplo
incluir	Você pode definir um caminho ou usar uma expressão regular para especificar todos os nós que deseja incluir. A inclusão de um diretório: incluir esse diretório e todos os arquivos e pastas desse diretório (ou seja, toda a subárvore) não incluir outros arquivos ou pastas no caminho raiz especificado	/libs/sling/install(/.*?lang=pt-BR)?
excluir	Você pode especificar um caminho ou usar uma expressão regular para especificar todos os nós que deseja excluir. A exclusão de um diretório excluirá esse diretório e todos os arquivos e pastas desse diretório (ou seja, toda a subárvore).	/libs/wcm/fundação/componentes(/.*?lang=pt-BR)?

Os filtros do pacote são definidos com mais frequência quando você cria o pacote, mas também podem ser editados posteriormente (após o que o pacote deve ser reconstruído).

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 o pacote contém. Isso é mostrado na lista do pacote e pode ajudá-lo 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 pacotes 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 em sua instalação AEM local. Depois que você atribuir as permissões necessárias, poderá usar o Gerenciador de pacotes para várias ações, incluindo 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.

Criando um Novo Pacote

Para criar uma nova definição de pacote:

1. Na tela AEM Welcome (Bem-vindo), clique em Packages (ou no duplo do console Ferramentas, clique em Packages).

2. Em seguida, selecione Gerenciador de pacotes.

3. Clique em Criar pacote.

   OBSERVAÇÃO

   Se a sua instância tiver muitos pacotes, pode haver uma estrutura de pastas em vigor, portanto, você pode navegar até a pasta de público alvo necessária antes de criar o novo pacote.

4. Na caixa de diálogo:

   

   Insira:

   • Nome do grupo

     O nome do grupo alvo (ou pasta). Os grupos devem ser usados para ajudá-lo a organizar seus pacotes.

     Uma pasta será criada para o grupo se ainda não existir. Se você deixar o nome do grupo em branco, ele criará o pacote na lista do pacote principal (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 esta página em um estágio posterior, se necessário.

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

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

   Clique em OK depois de terminar de editar as 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 com o duplo no componente de imagem na área Capturas de tela, adicionando uma imagem e clicando em OK.

8. Defina Filtros de pacote arrastando instâncias de Definição de filtro do sidekick e, em seguida, clicando no duplo para abrir para edição:

   

   Especifique:

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

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

     Se necessário, você pode definir Incluir ou Excluir regras 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 para posicioná-las conforme necessário usando os botões Up e Down.
     Em seguida, clique em OK para salvar o filtro.

   OBSERVAÇÃO

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

9. Para confirmar qual pacote contém, você pode usar Pré-visualização. Isso executa uma execução seca do processo de construção e lista tudo o que será adicionado ao pacote quando ele for realmente construído.

10. Agora você pode Criar seu pacote.

    OBSERVAÇÃO

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

Criação de um pacote

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

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

2. Clique em Build. 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ê estiver reconstruindo um pacote, já que o conteúdo do pacote será substituído.

3. Clique em OK. AEM criará o pacote, listando todo o conteúdo adicionado ao pacote conforme ele for criado. Quando concluído, o AEM exibe uma confirmação de que o pacote foi criado e (ao fechar a caixa de diálogo) atualiza as informações de lista do pacote.

Reenvolvimento de um Pacote

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

Revincular 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., ou seja, 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 a reembalagem é a preparação de uma embalagem. 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 sua funcionalidade (o que pode levar algum tempo e acarretar o risco de o pacote não ser mais idêntico ao original), você pode reembalá-lo e adicionar a miniatura e a descrição.

1. Abra a definição do pacote de 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 solicitará confirmação.

Visualizando e editando informações do pacote

Para visualização ou edição de informações sobre uma definição de pacote:

1. No Gerenciador de pacotes, navegue até o pacote que você deseja visualização.

2. Clique no ícone de pacote do pacote que deseja visualização. 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 a partir desta 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 Conteúdo, uma janela abrirá e lista todo o conteúdo do pacote:

Visualizando conteúdo do pacote e testando a instalação

Depois que um pacote for criado, você poderá visualização o conteúdo:

1. No Gerenciador de pacotes, navegue até o pacote que você deseja visualização.

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

3. Para visualização do conteúdo, clique em Conteúdo, uma janela abrirá e lista todo o conteúdo do pacote:

   

4. Para executar uma execução a seco da instalação, clique em Testar instalação. Depois de confirmar a ação, uma janela abrirá e lista os resultados como se a instalação tivesse sido executada:

   

Download de pacotes no seu sistema de arquivos

Esta seção descreve como baixar um pacote do AEM para seu sistema de arquivos usando 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 você deseja baixar; por exemplo export-for-offline.zip.

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

Carregando pacotes do seu sistema de arquivos

O upload de um pacote permite que você carregue um pacote de seu sistema de arquivos no Gerenciador de pacotes AEM.
Para carregar um pacote:

1. Navegue até Gerenciador de pacotes. Em seguida, para a pasta do grupo na qual você deseja que o pacote seja carregado.

   

2. Clique em Carregar pacote.

   

   • Arquivo

     Você pode digitar o nome do arquivo diretamente ou usar o Procurar…caixa de diálogo 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 do 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, verifique 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 da instalação.

Opções de validação

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

• Importações do pacote OSGi
• Sobreposições
• ACLs

Essas opções estão detalhadas abaixo.

• Validar importações do pacote OSGi

  O que está marcado

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

  Como é reportado

  Todas as dependências com versão que não possam ser atendidas pela instância AEM estão listadas em 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 start. Isso resulta em uma implantação de aplicativo quebrada, pois qualquer coisa que dependa do pacote OSGi não iniciado não funcionará corretamente.

  Resolução de erro

  Para resolver erros devido a pacotes OSGi não satisfeitos, a versão de dependência no pacote com importações não satisfeitas 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 AEM de destino.

  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 em 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 substituídas (e, portanto, "ocultas") pela sobreposição e não entrarão em vigor.

  Resolução de erro

  Para resolver esse problema, o responsável principal 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 reportar 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 em Log de Atividades do Gerenciador de pacotes.

  Estados de erro

  Não é possível fornecer erros explícitos. A validação simplesmente indica se novas permissões de ACL serão adicionadas ou afetadas 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 ser ajustadas no pacote conforme necessário.

  CUIDADO

  Como prática recomendada, os pacotes não devem afetar as ACLs fornecidas pelo AEM, pois isso pode resultar em comportamento inesperado do produto.

Executando Validação

A validação dos pacotes pode ser efetuada de duas formas diferentes:

• Por meio da interface do usuário do Gerenciador de pacotes
• Por solicitação POST HTTP, 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, em seguida, selecione Mais no menu suspenso e, em seguida, 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 é exibida, 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 de POST HTTP

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

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

A seguir está um exemplo de uso de cURL para executar uma validação de pacote.

1. Se você estiver usando cURL, execute uma instrução semelhante à 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 carregar um pacote, é necessário instalar o conteúdo. Para ter o conteúdo do pacote instalado e funcional, ele precisa ser:

• carregado no AEM (carregado do sistema de arquivos ou baixado de Distribuição de software)

• instalados

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

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

   OBSERVAÇÃO

   Como alternativa, você pode abrir o pacote clicando em seu ícone para acessar o botão Instalar ali.

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

   A palavra Instalado aparece ao lado do pacote depois que ele é instalado.

Upload e instalação baseados no sistema de arquivos

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

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

Se sua instância estiver sendo executada, a adição de um pacote à pasta install iniciará diretamente o upload e a instalação na instância. Se sua instância não estiver em execução, os pacotes que você colocar na pasta install serão instalados na inicialização, na ordem alfabética.

Desinstalação de pacotes

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

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

Excluindo pacotes

Para excluir um pacote das listas do Gerenciador de pacotes:

1. No console Ferramentas, expanda a pasta Pacotes para mostrar seu pacote no painel direito.

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

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

   

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

Replicação de 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 você 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 era um servidor centralizado disponibilizado publicamente para compartilhar Content-Packages.

Ela foi substituída por Software Distribution.

Distribuição de software

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

Para obter mais informações, consulte a documentação de Distribuição de software.