Upload de ativo programático no AEM as a Cloud Service
Saiba como carregar ativos para o ambiente do AEM as a Cloud Service usando o aplicativo cliente que usa a biblioteca Node.js aem-upload.
O que você aprenderá
Neste tutorial, você aprenderá:
- Como usar a abordagem de upload binário direto para carregar ativos para o ambiente do AEM as a Cloud Service (RDE, Desenvolvimento, Preparo, Produção) usando a biblioteca Node.js aem-upload.
- Como configurar e executar o aplicativo aem-asset-upload-sample para carregar ativos para o ambiente do AEM as a Cloud Service.
- Revise o código do aplicativo de amostra e entenda os detalhes de implementação.
- Entenda as práticas recomendadas para o upload de ativos programático no ambiente do AEM as a Cloud Service.
Entendendo a abordagem upload binário direto
A abordagem de carregamento binário direto permite carregar arquivos do sistema de origem diretamente para o armazenamento na nuvem no ambiente do AEM as a Cloud Service usando uma URL pré-assinada. Ele elimina a necessidade de rotear dados binários por meio dos processos Java da AEM, resultando em uploads mais rápidos e carga reduzida do servidor.
Antes de executar o aplicativo de amostra, vamos entender o fluxo de upload binário direto.
No fluxo de upload binário direto, os dados binários são carregados diretamente no armazenamento em nuvem com URLs pré-assinados. O AEM as a Cloud Service é responsável pelo processamento leve, como gerar os URLs pré-assinados e notificar o AEM Asset Compute Service sobre a conclusão do upload. O diagrama de fluxo lógico a seguir ilustra o fluxo de upload binário direto.
A biblioteca de upload do aem
A biblioteca Node.js aem-upload abstrai os detalhes de implementação da abordagem de upload binário direto. Ela fornece duas classes para orquestrar o processo de upload:
- FileSystemUpload - Use-o ao carregar arquivos do sistema de arquivos local, incluindo suporte para estruturas de diretório
- DirectBinaryUpload - Use-o para obter um controle mais polido sobre o processo de carregamento binário, como o carregamento de fluxos ou buffers
Aplicativo de amostra
Use o aplicativo aem-asset-upload-sample para saber mais sobre o processo de carregamento de ativos programático. O aplicativo de amostra demonstra o uso das classes FileSystemUpload e DirectBinaryUpload da biblioteca aem-upload.
Pré-requisitos
Antes de executar o aplicativo de amostra, verifique os seguintes pré-requisitos:
- Ambiente de criação do AEM as a Cloud Service, como RDE (Rapid Development Environment, ambiente de desenvolvimento rápido), ambiente de desenvolvimento etc.
- Node.js (versão LTS mais recente)
- Noções básicas sobre Node.js e npm
Baixar o aplicativo de amostra
-
Baixe o arquivo zip do aplicativo aem-asset-upload-sample e extraia-o.
code language-bash $ unzip aem-asset-upload-sample.zip -
Abra a pasta extraída no editor de código favorito.
code language-bash $ cd aem-asset-upload-sample $ code . -
Usando o terminal do editor de código, instale as dependências.
code language-bash $ npm install
Configurar o aplicativo de amostra
Antes de executar o aplicativo de amostra, você deve configurá-lo com os detalhes necessários do ambiente do AEM as a Cloud Service, como a URL do autor do AEM, o método de autenticação e o caminho da pasta de ativos.
Há vários métodos de autenticação compatíveis com a biblioteca Node.js aem-upload. A tabela a seguir resume os métodos de autenticação com suporte e sua finalidade.
Para configurar o aplicativo de amostra, siga as etapas abaixo:
-
Copie o arquivo
env.examplepara o arquivo.env.code language-bash $ cp env.example .env -
Abra o arquivo
.enve atualize a variável de ambienteAEM_URLcom a URL do autor do AEM as a Cloud Service. -
Escolha o método de autenticação nas opções a seguir e atualize as variáveis de ambiente correspondentes.
Para usar a autenticação básica, é necessário criar um usuário no ambiente do AEM as a Cloud Service.
-
Faça logon no ambiente do AEM as a Cloud Service.
-
Navegue até Ferramentas > Segurança > Usuários e clique no botão Criar.
-
Insira os detalhes do usuário
-
Na guia Grupos, adicione o grupo Usuários DAM. Clique no botão Salvar e fechar.
-
Atualize as variáveis de ambiente
AEM_USERNAMEeAEM_PASSWORDcom o nome de usuário e a senha do usuário criado.
Para obter o token de desenvolvimento local, é necessário usar o Developer Console AEM. O token gerado é do tipo JSON Web Token (JWT).
-
Faça logon no Adobe Cloud Manager e navegue até a página de detalhes do Ambiente desejado. Clique no “…” e selecione Developer Console.
-
Faça logon no AEM Developer Console e use o botão Novo Console para alternar para o console mais recente.
-
Na seção Ferramentas, selecione Integrações e clique no botão Obter token local.
-
Copie o valor do token e atualize a variável de ambiente
AEM_BEARER_TOKENcom o valor do token.
Observe que o token de desenvolvimento local é válido por 24 horas e é emitido para o usuário que gerou o token.
Para obter as credenciais do serviço, é necessário usar o Developer Console AEM. Ele é usado para gerar o token do tipo JSON Web Token (JWT) usando o módulo jwt-auth npm.
-
Faça logon no Adobe Cloud Manager e navegue até a página de detalhes do Ambiente desejado. Clique no “…” e selecione Developer Console.
-
Faça logon no AEM Developer Console e use o botão Novo Console para alternar para o console mais recente.
-
Na seção Ferramentas, selecione Integrações e clique no botão Criar nova conta técnica.
-
Clique na opção Exibir para copiar as credenciais de serviço JSON.
-
Crie um arquivo
service-credentials.jsonna raiz do aplicativo de amostra e cole as credenciais de serviço JSON no arquivo. -
Atualize a variável de ambiente
AEM_SERVICE_CREDENTIALS_FILEcom o caminho para o arquivo service-credentials.json. -
Verifique se o usuário da credencial de serviço tem as permissões necessárias para carregar ativos no ambiente do AEM as a Cloud Service. Para obter mais informações, consulte Configurar acesso na página AEM.
Aqui está o arquivo de amostra .env completo com todos os três métodos de autenticação configurados.
# AEM Environment Configuration
# Copy this file to .env and fill in your AEM as a Cloud Service details
# AEM as a Cloud Service Author URL (without trailing slash)
# Example: https://author-p12345-e67890.adobeaemcloud.com
AEM_URL=https://author-p63947-e1733365.adobeaemcloud.com
# Upload Configuration
# Target folder in AEM DAM where assets will be uploaded
TARGET_FOLDER=/content/dam
# DirectBinaryUpload Remote URLs (required for DirectBinaryUpload example)
# URLs for remote files to upload in the DirectBinaryUpload example
# These demonstrate uploading from remote sources (URLs, CDNs, APIs)
REMOTE_FILE_URL_1=https://placehold.co/600x400/red/white?text=Adobe+Experience+Manager+Assets
################################################################
# Authentication - Choose one of the following methods:
################################################################
# Method 1: Service Credentials (RECOMMENDED for production)
# Download service credentials JSON from AEM Developer Console and save it locally
# Then provide the path to the file here
AEM_SERVICE_CREDENTIALS_FILE=./service-credentials.json
# Method 2: Bearer Token Authentication (for manual testing)
AEM_BEARER_TOKEN=eyJhbGciOiJSUzI1NiIsIng1dSI6Imltc19uYTEta2V5LWF0LTEuY2VyIiwia2lkIjoiaW1zX25hM....fsdf-Rgt5hm_8FHutTyNQnkj1x1SUs5OkqUfJaGBaKBKdqQ
# Method 3: Basic Authentication (for development/testing only)
AEM_USERNAME=asset-uploader-local-user
AEM_PASSWORD=asset-uploader-local-user
# Optional: Enable detailed logging
DEBUG=false
Execute o aplicativo de amostra
O aplicativo de amostra mostra três maneiras diferentes de fazer upload de ativos de amostra para o ambiente do AEM as a Cloud Service.
- FileSystemUpload - Fazer upload de arquivos de um sistema de arquivos local com suporte à estrutura de diretórios e criação automática de pastas
- DirectBinaryUpload - Carrega um arquivo remoto. O binário do arquivo é armazenado em buffer na memória antes de ser carregado no ambiente do AEM as a Cloud Service.
- Carregamento em lote - Faz upload de vários arquivos de um sistema de arquivos local em lotes com lógica de repetição automática e recuperação de erros. Em segundo plano, ele usa a classe
FileSystemUploadpara carregar arquivos do sistema de arquivos local.
Os ativos a serem carregados estão localizados na pasta sample-assets e contêm subpastas img, video e doc, cada uma contendo alguns ativos de amostra.
- Para executar o aplicativo de amostra, use o seguinte comando:
$ npm start
- Insira a opção desejada número entre as seguintes opções:
╔════════════════════════════════════════════════════════════╗
║ AEM Asset Upload Sample Application ║
║ Demonstrating @adobe/aem-upload library ║
╚════════════════════════════════════════════════════════════╝
Choose an upload method:
1. FileSystemUpload - Upload files from local filesystem with auto-folder creation
2. DirectBinaryUpload - Upload from remote URLs/streams to AEM
3. Batch Upload - Upload multiple files in batches with retry logic
4. Exit
As guias a seguir mostram a execução do aplicativo de amostra, sua saída e os ativos carregados no ambiente do AEM as a Cloud Service para cada método de upload.
- A saída do aplicativo de exemplo para a opção
FileSystemUpload:
| code language-bash |
|---|
|
-
Assets carregado usando a opção
FileSystemUploadno ambiente AEM as a Cloud Service:
- A saída do aplicativo de exemplo para a opção
DirectBinaryUpload:
| code language-bash |
|---|
|
- Assets carregado usando a opção
DirectBinaryUploadno ambiente AEM as a Cloud Service:
- A saída do aplicativo de exemplo para a opção
Batch Upload:
| code language-bash |
|---|
|
- Assets carregado usando a opção
Batch Uploadno ambiente AEM as a Cloud Service:
Revisar o código do aplicativo de exemplo
O principal ponto de entrada do aplicativo de amostra é o arquivo index.js. Ele contém a função promptUser que solicita uma escolha ao usuário e executa o exemplo selecionado.
/**
* Prompts user for choice and executes the selected example
*/
function promptUser() {
rl.question(chalk.bold('Enter your choice (1-4): '), async (answer) => {
console.log('');
try {
switch (answer.trim()) {
case '1':
console.log(chalk.bold.green('\n▶ Running FileSystemUpload Example...\n'));
await filesystemUpload.main();
break;
case '2':
console.log(chalk.bold.green('\n▶ Running DirectBinaryUpload Example...\n'));
await directBinaryUpload.main();
break;
case '3':
console.log(chalk.bold.green('\n▶ Running Batch Upload Example...\n'));
await batchUpload.main();
break;
case '4':
rl.close();
return;
default:
console.log(chalk.red('\n✗ Invalid choice. Please enter 1, 2, 3, or 4.\n'));
}
// After example completes, ask if user wants to continue
rl.question(chalk.bold('\nPress Enter to return to menu or Ctrl+C to exit...'), () => {
displayMenu();
promptUser();
});
} catch (error) {
console.error(chalk.red('\n✗ Error:'), error.message);
rl.question(chalk.bold('\nPress Enter to return to menu...'), () => {
displayMenu();
promptUser();
});
}
});
}
Para obter o código completo, consulte o arquivo index.js do aplicativo de amostra.
As guias a seguir mostram os detalhes de implementação de cada método de upload.
A classe FileSystemUpload é usada para carregar arquivos do sistema de arquivos local com suporte à estrutura de diretório e criação automática de pastas.
| code language-javascript |
|---|
|
Para obter o código completo, consulte o arquivo examples/filesystem-upload.js do aplicativo de amostra.
A classe DirectBinaryUpload é usada para carregar um arquivo remoto para o ambiente AEM as a Cloud Service.
| code language-javascript |
|---|
|
Para obter o código completo, consulte o arquivo examples/direct-binary-upload.js do aplicativo de amostra.
Ele divide os arquivos em lotes e os carrega em lotes com lógica de repetição automática e recuperação de erros. Em segundo plano, ele usa a classe FileSystemUpload para carregar arquivos do sistema de arquivos local.
| code language-javascript |
|---|
|
Para obter o código completo, consulte o arquivo examples/batch-upload.js do aplicativo de amostra.
Além disso, o arquivo README.md do aplicativo de amostra contém a documentação detalhada para o aplicativo de amostra.
Práticas recomendadas
-
Escolha o método de autenticação correto:
Use credenciais de serviço para ambientes de produção, token de desenvolvimento local e autenticação básica apenas para desenvolvimento/teste. Verifique se o usuário da credencial de serviço tem as permissões necessárias para carregar ativos no ambiente do AEM as a Cloud Service. -
Escolha o método de carregamento correto:
Use FileSystemUpload para arquivos locais com criação automática de pasta, DirectBinaryUpload para fluxos/buffers/URLs remotos com controle refinado e padrão de Upload em lote para ambientes de produção com mais de 1000 arquivos que exigem lógica de repetição. -
Objetos de arquivo DirectBinaryUpload de estrutura corretamente
Use a propriedade blob (não buffer) com os campos obrigatórios: { fileName, fileSize, blob: buffer, targetFolder } e lembre-se de que DirectBinaryUpload NÃO cria pastas automaticamente. -
Aplicativo de exemplo como referência:
O aplicativo de amostra é uma boa referência para os detalhes de implementação do processo de upload de ativos programáticos. Você pode usá-lo como ponto de partida para sua própria implementação do.