Carga de recursos mediante programación en AEM as a Cloud Service
Aprenda a cargar recursos en el entorno de AEM as a Cloud Service mediante la aplicación cliente que usa la biblioteca aem-upload Node.js.
Qué aprenderá
En este tutorial, aprenderá lo siguiente:
- Cómo usar el método de carga binaria directa para cargar recursos al entorno de AEM as a Cloud Service (RDE, Dev, Stage, Prod) usando la biblioteca aem-upload Node.js.
- Configurar y ejecutar la aplicación aem-asset-upload-sample para cargar recursos en el entorno de AEM as a Cloud Service.
- Revise el código de la aplicación de ejemplo y comprenda los detalles de la implementación.
- Conozca las prácticas recomendadas para la carga programática de recursos en el entorno de AEM as a Cloud Service.
Entender el enfoque de carga binaria directa
El método de carga binaria directa le permite cargar archivos de su sistema de origen directamente al almacenamiento en la nube en el entorno de AEM as a Cloud Service mediante una URL con firma previa. Esto elimina la necesidad de enrutar los datos binarios a través de los procesos Java de AEM, lo que resulta en cargas más rápidas y una carga del servidor reducida.
Antes de ejecutar la aplicación de ejemplo, vamos a comprender el flujo de carga binaria directa.
En el flujo de carga binaria directa, los datos binarios se cargan directamente en el almacenamiento en la nube con direcciones URL prefirmadas. AEM as a Cloud Service es responsable del procesamiento ligero, como la generación de las direcciones URL prefirmadas y la notificación al servicio AEM Asset Compute de la finalización de la carga. El siguiente diagrama de flujo lógico ilustra el flujo de carga binario directo.
La biblioteca de carga de aem
La biblioteca aem-upload Node.js resume los detalles de implementación del enfoque carga binaria directa. Proporciona dos clases para organizar el proceso de carga:
- FileSystemUpload: utilícelo al cargar archivos del sistema de archivos local, incluida la compatibilidad con estructuras de directorio
- DirectBinaryUpload: utilícelo para tener un control más preciso sobre el proceso de carga binaria, como la carga desde secuencias o búferes
Aplicación de ejemplo
Utilice la aplicación aem-asset-upload-sample para conocer el proceso programático de carga de recursos. La aplicación de ejemplo muestra el uso de las clases FileSystemUpload y DirectBinaryUpload de la biblioteca aem-upload.
Requisitos previos
Antes de ejecutar la aplicación de ejemplo, asegúrese de que tiene los siguientes requisitos previos:
- Entorno de creación de AEM as a Cloud Service, como el entorno de desarrollo rápido (RDE), el entorno de desarrollo, etc.
- Node.js (última versión de LTS)
- Comprensión básica de Node.js y npm
Descargar la aplicación de ejemplo
-
Descargue el archivo zip de la aplicación aem-asset-upload-sample y extráigalo.
code language-bash $ unzip aem-asset-upload-sample.zip -
Abra la carpeta extraída en su editor de código favorito.
code language-bash $ cd aem-asset-upload-sample $ code . -
Mediante el terminal del editor de código, instale las dependencias.
code language-bash $ npm install
Configurar la aplicación de ejemplo
Antes de ejecutar la aplicación de ejemplo, debe configurarla con los detalles necesarios del entorno de AEM as a Cloud Service, como la URL del autor de AEM, el método de autenticación y la ruta de la carpeta de recursos.
La biblioteca aem-upload Node.js admite varios métodos de autenticación. La siguiente tabla resume los métodos de autenticación admitidos y su propósito.
Para configurar la aplicación de ejemplo, siga los pasos a continuación:
-
Copie el archivo
env.exampleen el archivo.env.code language-bash $ cp env.example .env -
Abra el archivo
.envy actualice la variable de entornoAEM_URLcon la dirección URL del autor de AEM as a Cloud Service. -
Elija el método de autenticación de las siguientes opciones y actualice las variables de entorno correspondientes.
Para utilizar la autenticación básica, debe crear un usuario en el entorno de AEM as a Cloud Service.
-
Inicie sesión en su entorno de AEM as a Cloud Service.
-
Vaya a Herramientas > Seguridad > Usuarios y haga clic en el botón Crear.
-
Introduzca los detalles del usuario
-
En la ficha Grupos, agregue el grupo Usuarios de DAM. Haga clic en el botón Guardar y cerrar.
-
Actualice las variables de entorno
AEM_USERNAMEyAEM_PASSWORDcon el nombre de usuario y la contraseña del usuario creado.
Para obtener el token de desarrollo local, debes usar el Developer Console AEM. El token generado es del tipo token web JSON (JWT).
-
Inicie sesión en Adobe Cloud Manager y vaya a la página de detalles de Entorno que desee. Haga clic en “…” y seleccione Developer Console.
-
Inicie sesión en AEM Developer Console y use el botón Nueva consola para cambiar a la consola más reciente.
-
En la sección Herramientas, seleccione Integraciones y haga clic en el botón Obtener token local.
-
Copie el valor del token y actualice la variable de entorno
AEM_BEARER_TOKENcon el valor del token.
Tenga en cuenta que el token de desarrollo local es válido durante 24 horas y se emite para el usuario que generó el token.
Para obtener las credenciales del servicio, debes usar el Developer Console AEM. Se usa para generar el token de tipo JSON Web Token (JWT) usando el módulo jwt-auth npm.
-
Inicie sesión en Adobe Cloud Manager y vaya a la página de detalles de Entorno que desee. Haga clic en “…” y seleccione Developer Console.
-
Inicie sesión en AEM Developer Console y use el botón Nueva consola para cambiar a la consola más reciente.
-
En la sección Herramientas, seleccione Integraciones y haga clic en el botón Crear nueva cuenta técnica.
-
Haga clic en la opción Ver para copiar las credenciales del servicio JSON.
-
Cree un archivo
service-credentials.jsonen la raíz de la aplicación de ejemplo y pegue las credenciales del servicio JSON en el archivo. -
Actualice la variable de entorno
AEM_SERVICE_CREDENTIALS_FILEcon la ruta al archivo service-credentials.json. -
Asegúrese de que el usuario de credenciales de servicio tenga los permisos necesarios para cargar recursos en el entorno de AEM as a Cloud Service. Para obtener más información, consulte la página Configurar el acceso en AEM.
Este es un archivo de muestra .env completo con los tres métodos de autenticación 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
Ejecute la aplicación de ejemplo
La aplicación de ejemplo muestra tres formas diferentes de cargar recursos de muestra en el entorno de AEM as a Cloud Service.
- FileSystemUpload - Cargar archivos desde un sistema de archivos local con compatibilidad con la estructura de directorios y creación automática de carpetas
- DirectBinaryUpload - Carga un archivo remoto. El binario de archivo se almacena en búfer antes de cargarse en el entorno de AEM as a Cloud Service.
- Carga por lotes: carga varios archivos desde un sistema de archivos local por lotes con lógica de reintento automática y recuperación de errores. En segundo plano, utiliza la clase
FileSystemUploadpara cargar archivos desde el sistema de archivos local.
Los recursos que se van a cargar se encuentran en la carpeta sample-assets y contienen las subcarpetas img, video y doc, cada una de las cuales contiene algunos recursos de ejemplo.
- Para ejecutar la aplicación de ejemplo, utilice el siguiente comando:
$ npm start
- Escriba la opción number que desee entre las siguientes opciones:
╔════════════════════════════════════════════════════════════╗
║ 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
Las siguientes pestañas muestran la ejecución de la aplicación de ejemplo, su salida y los recursos cargados en el entorno de AEM as a Cloud Service para cada método de carga.
- Salida de la aplicación de ejemplo para la opción
FileSystemUpload:
| code language-bash |
|---|
|
-
Assets cargado con la opción
FileSystemUploaden el entorno de AEM as a Cloud Service:
- Salida de la aplicación de ejemplo para la opción
DirectBinaryUpload:
| code language-bash |
|---|
|
- Assets cargado con la opción
DirectBinaryUploaden el entorno de AEM as a Cloud Service:
- Salida de la aplicación de ejemplo para la opción
Batch Upload:
| code language-bash |
|---|
|
- Assets cargado con la opción
Batch Uploaden el entorno de AEM as a Cloud Service:
Revise el código de aplicación de ejemplo
El punto de entrada principal de la aplicación de ejemplo es el archivo index.js. Contiene la función promptUser que solicita al usuario una opción y ejecuta el ejemplo seleccionado.
/**
* 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 obtener el código completo, consulte el archivo index.js de la aplicación de ejemplo.
Las siguientes pestañas muestran los detalles de implementación de cada método de carga.
La clase FileSystemUpload se usa para cargar archivos del sistema de archivos local con compatibilidad con la estructura de directorios y creación automática de carpetas.
| code language-javascript |
|---|
|
Para obtener el código completo, consulte el archivo examples/filesystem-upload.js de la aplicación de ejemplo.
La clase DirectBinaryUpload se usa para cargar un archivo remoto en el entorno de AEM as a Cloud Service.
| code language-javascript |
|---|
|
Para obtener el código completo, consulte el archivo examples/direct-binary-upload.js de la aplicación de ejemplo.
Divide los archivos en lotes y los carga en lotes con lógica de reintento automática y recuperación de errores. En segundo plano, utiliza la clase FileSystemUpload para cargar archivos desde el sistema de archivos local.
| code language-javascript |
|---|
|
Para obtener el código completo, consulte el archivo examples/batch-upload.js de la aplicación de ejemplo.
Además, el archivo README.md de la aplicación de ejemplo contiene la documentación detallada de la aplicación de ejemplo.
Prácticas recomendadas
-
Elija el método de autenticación adecuado:
Utilice credenciales de servicio para entornos de producción, token de desarrollo local y autenticación básica solo para desarrollo y pruebas. Asegúrese de que el usuario de credenciales de servicio tenga los permisos necesarios para cargar recursos en el entorno de AEM as a Cloud Service. -
Elija el método de carga adecuado:
Utilice FileSystemUpload para archivos locales con creación automática de carpetas, DirectBinaryUpload para secuencias, búferes o direcciones URL remotas con control preciso y patrón de carga por lotes para entornos de producción con más de 1000 archivos que requieren lógica de reintento. -
Estructurar correctamente los objetos del archivo DirectBinaryUpload
Utilice la propiedad blob (no el búfer) con los campos obligatorios: { fileName, fileSize, blob: buffer, targetFolder } y recuerde que DirectBinaryUpload NO crea carpetas automáticamente. -
Aplicación de muestra como referencia:
La aplicación de ejemplo es una buena referencia para los detalles de implementación del proceso de carga de recursos mediante programación. Puede utilizarlo como punto de partida para su propia implementación.