Caricamento di risorse programmatiche in AEM as a Cloud Service
Scopri come caricare le risorse nell’ambiente AEM as a Cloud Service utilizzando l’applicazione client che utilizza la libreria Node.js aem-upload.
Argomenti trattati
In questa esercitazione imparerai:
- Come utilizzare l’approccio caricamento binario diretto per caricare le risorse nell’ambiente AEM as a Cloud Service (RDE, Dev, Stage, Prod) utilizzando la libreria aem-upload Node.js.
- Come configurare ed eseguire l’applicazione aem-asset-upload-sample per caricare risorse nell’ambiente AEM as a Cloud Service.
- Esamina il codice dell’applicazione di esempio e comprendi i dettagli di implementazione.
- Scopri le best practice per il caricamento programmatico delle risorse nell’ambiente AEM as a Cloud Service.
Informazioni sull’approccio caricamento binario diretto
L’approccio di caricamento binario diretto consente di caricare i file dal sistema di origine direttamente nell’archiviazione cloud nell’ambiente AEM as a Cloud Service utilizzando un URL preceduto. Elimina la necessità di instradare i dati binari attraverso i processi Java di AEM, velocizzando i caricamenti e riducendo il carico del server.
Prima di eseguire l’applicazione di esempio, comprendiamo il flusso di caricamento binario diretto.
Nel flusso di caricamento binario diretto, i dati binari vengono caricati direttamente nell’archiviazione cloud con URL prefirmati. L’AEM as a Cloud Service è responsabile dell’elaborazione leggera, ad esempio la generazione degli URL prefirmati e la notifica al servizio AEM Asset Compute del completamento del caricamento. Il seguente diagramma di flusso logico illustra il flusso di caricamento binario diretto.
Libreria di caricamento AEM
La libreria aem-upload Node.js astrae i dettagli di implementazione dell’approccio direct binary upload. Fornisce due classi per orchestrare il processo di caricamento:
- FileSystemUpload - Utilizzarlo per caricare i file dal file system locale, incluso il supporto per le strutture di directory
- DirectBinaryUpload - Utilizzalo per un controllo più dettagliato sul processo di caricamento binario, ad esempio per il caricamento da flussi o buffer
Applicazione di esempio
Utilizza l’applicazione aem-asset-upload-sample per apprendere il processo di caricamento programmatico delle risorse. L’applicazione di esempio illustra l’utilizzo di entrambe le classi FileSystemUpload e DirectBinaryUpload della libreria aem-upload.
Prerequisiti
Prima di eseguire l’applicazione di esempio, verificare di disporre dei seguenti prerequisiti:
- Ambiente di authoring di AEM as a Cloud Service come ambiente di sviluppo rapido (RDE), ambiente di sviluppo, ecc.
- Node.js (ultima versione LTS)
- Node.js e npm: nozioni di base
Scarica l’applicazione di esempio
-
Scarica il file zip dell’applicazione aem-asset-upload-sample ed estrailo.
code language-bash $ unzip aem-asset-upload-sample.zip -
Apri la cartella estratta nel tuo editor di codice preferito.
code language-bash $ cd aem-asset-upload-sample $ code . -
Utilizzando il terminale dell’editor di codice, installa le dipendenze.
code language-bash $ npm install
Configurare l’applicazione di esempio
Prima di eseguire l’applicazione di esempio, è necessario configurarla con i dettagli dell’ambiente AEM as a Cloud Service necessari, come l’URL di AEM Author, il metodo di autenticazione e il percorso della cartella delle risorse.
Sono disponibili più metodi di autenticazione supportati dalla libreria aem-upload Node.js. Nella tabella seguente sono riepilogati i metodi di autenticazione supportati e il relativo scopo.
Per configurare l’applicazione di esempio, effettua le seguenti operazioni:
-
Copiare il file
env.examplenel file.env.code language-bash $ cp env.example .env -
Apri il file
.enve aggiorna la variabile di ambienteAEM_URLcon l’URL di authoring di AEM as a Cloud Service. -
Scegli il metodo di autenticazione tra le seguenti opzioni e aggiorna le variabili di ambiente corrispondenti.
Per utilizzare l’autenticazione di base, è necessario creare un utente nell’ambiente AEM as a Cloud Service.
-
Accedi all’ambiente AEM as a Cloud Service.
-
Passa a Strumenti > Sicurezza > Utenti e fai clic sul pulsante Crea.
-
Immetti i dettagli utente
-
Nella scheda Groups, aggiungi il gruppo DAM Users. Fare clic sul pulsante Salva e chiudi.
-
Aggiornare le variabili di ambiente
AEM_USERNAMEeAEM_PASSWORDcon il nome utente e la password dell’utente creato.
Per ottenere il token di sviluppo locale, è necessario utilizzare il Developer Console AEM. Il token generato è di tipo JSON Web Token (JWT).
-
Accedi a Adobe Cloud Manager e passa alla pagina dei dettagli Ambiente desiderata. Fare clic su “…” e selezionare Developer Console.
-
Accedi ad AEM Developer Console e utilizza il pulsante Nuova console per passare alla console più recente.
-
Dalla sezione Strumenti, seleziona Integrazioni e fai clic sul pulsante Ottieni token locale.
-
Copiare il valore del token e aggiornare la variabile di ambiente
AEM_BEARER_TOKENcon il valore del token.
Il token di sviluppo locale è valido per 24 ore ed è rilasciato per l’utente che lo ha generato.
Per ottenere le credenziali del servizio, è necessario utilizzare il Developer Console AEM. Viene utilizzato per generare il token del tipo JSON Web Token (JWT) utilizzando il modulo jwt-auth npm.
-
Accedi a Adobe Cloud Manager e passa alla pagina dei dettagli Ambiente desiderata. Fare clic su “…” e selezionare Developer Console.
-
Accedi ad AEM Developer Console e utilizza il pulsante Nuova console per passare alla console più recente.
-
Dalla sezione Strumenti, seleziona Integrazioni e fai clic sul pulsante Crea nuovo account tecnico.
-
Fai clic sull’opzione Visualizza per copiare le credenziali del servizio JSON.
-
Creare un file
service-credentials.jsonnella radice dell’applicazione di esempio e incollare le credenziali del servizio JSON nel file. -
Aggiornare la variabile di ambiente
AEM_SERVICE_CREDENTIALS_FILEcon il percorso del file service-credentials.json. -
Assicurati che l’utente con le credenziali del servizio disponga delle autorizzazioni necessarie per caricare le risorse nell’ambiente AEM as a Cloud Service. Per ulteriori informazioni, vedere Configurare l’accesso nella pagina AEM.
Ecco il file .env completo con tutti e tre i metodi di autenticazione configurati.
# 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
Eseguire l’applicazione di esempio
L’applicazione di esempio mostra tre modi diversi per caricare le risorse di esempio nell’ambiente AEM as a Cloud Service.
- FileSystemUpload - Carica i file da un file system locale con supporto per la struttura delle directory e creazione automatica delle cartelle
- DirectBinaryUpload - Carica un file remoto. Il file binario viene inserito nel buffer della memoria prima di essere caricato nell’ambiente AEM as a Cloud Service.
- Caricamento batch - Carica più file da un file system locale in batch con logica automatica di esecuzione di nuovi tentativi e recupero degli errori. Dietro le quinte, utilizza la classe
FileSystemUploadper caricare i file dal file system locale.
Le risorse da caricare si trovano nella cartella sample-assets e contengono img, video e doc sottocartelle, ognuna contenente alcune risorse di esempio.
- Per eseguire l’applicazione di esempio, utilizzare il comando seguente:
$ npm start
- Immetti l’opzione desiderata numero tra le seguenti scelte:
╔════════════════════════════════════════════════════════════╗
║ 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
Le schede seguenti mostrano l’esecuzione dell’applicazione di esempio, il relativo output e le risorse caricate nell’ambiente AEM as a Cloud Service per ogni metodo di caricamento.
- L’output dell’applicazione di esempio per l’opzione
FileSystemUpload:
| code language-bash |
|---|
|
-
Assets caricato con l’opzione
FileSystemUploadnell’ambiente AEM as a Cloud Service:
- L’output dell’applicazione di esempio per l’opzione
DirectBinaryUpload:
| code language-bash |
|---|
|
- Assets caricato con l’opzione
DirectBinaryUploadnell’ambiente AEM as a Cloud Service:
- L’output dell’applicazione di esempio per l’opzione
Batch Upload:
| code language-bash |
|---|
|
- Assets caricato con l’opzione
Batch Uploadnell’ambiente AEM as a Cloud Service:
Esamina il codice dell’applicazione di esempio
Il punto di ingresso principale dell’applicazione di esempio è il file index.js. Contiene la funzione promptUser che richiede all’utente una scelta ed esegue l’esempio selezionato.
/**
* 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();
});
}
});
}
Per il codice completo, fare riferimento al file index.js dell’applicazione di esempio.
Le schede seguenti mostrano i dettagli di implementazione di ciascun metodo di caricamento.
La classe FileSystemUpload viene utilizzata per caricare file dal file system locale con supporto per la struttura delle directory e creazione automatica delle cartelle.
| code language-javascript |
|---|
|
Per il codice completo, fare riferimento al file examples/filesystem-upload.js dell’applicazione di esempio.
La classe DirectBinaryUpload viene utilizzata per caricare un file remoto nell’ambiente AEM as a Cloud Service.
| code language-javascript |
|---|
|
Per il codice completo, fare riferimento al file examples/direct-binary-upload.js dell’applicazione di esempio.
Divide i file in batch e li carica in batch con logica automatica di esecuzione di nuovi tentativi e recupero degli errori. Dietro le quinte, utilizza la classe FileSystemUpload per caricare i file dal file system locale.
| code language-javascript |
|---|
|
Per il codice completo, fare riferimento al file examples/batch-upload.js dell’applicazione di esempio.
Inoltre, il file README.md dell’applicazione di esempio contiene la documentazione dettagliata dell’applicazione di esempio.
Best practice
-
Scegliere il metodo di autenticazione corretto:
Utilizza le credenziali del servizio solo per gli ambienti di produzione, il token di sviluppo locale e l’autenticazione di base per lo sviluppo e i test. Assicurati che l’utente con le credenziali del servizio disponga delle autorizzazioni necessarie per caricare le risorse nell’ambiente AEM as a Cloud Service. -
Scegliere il metodo di caricamento corretto:
Utilizzare FileSystemUpload per i file locali con creazione automatica della cartella, DirectBinaryUpload per flussi/buffer/URL remoti con controllo dettagliato e Batch Upload pattern per gli ambienti di produzione con più di 1000 file che richiedono una logica di ripetizione dei tentativi. -
Struttura oggetti file DirectBinaryUpload correttamente
Utilizza la proprietà blob (non il buffer) con i campi obbligatori: { fileName, fileSize, blob: buffer, targetFolder } e ricorda che DirectBinaryUpload NON crea automaticamente cartelle. -
Esempio di applicazione come riferimento:
L’applicazione di esempio è un buon riferimento per i dettagli di implementazione del processo di caricamento delle risorse a livello di programmazione. Puoi utilizzarlo come punto di partenza per la tua implementazione.