Chargement de ressources par programme vers AEM as a Cloud Service
Découvrez comment charger des ressources dans un environnement AEM as a Cloud Service à l’aide de l’application cliente qui utilise la bibliothèque Node.js aem-upload.
Ce que vous apprenez
Dans ce tutoriel, vous apprenez ce qui suit :
- Comment utiliser l’approche chargement binaire direct pour charger des ressources dans l’environnement AEM as a Cloud Service (RDE, développement, évaluation et production) à l’aide de la bibliothèque Node.js aem-upload.
- Comment configurer et exécuter l’application aem-asset-upload-sample pour charger des ressources dans l’environnement AEM as a Cloud Service.
- Consultez l’exemple de code d’application et comprenez les détails d’implémentation.
- Découvrez les bonnes pratiques relatives au chargement de ressources par programmation dans l’environnement AEM as a Cloud Service.
Comprendre l’approche chargement binaire direct
L’approche chargement binaire direct permet de charger des fichiers à partir de votre système source directement vers l’espace de stockage dans un environnement AEM as a Cloud Service à l’aide d’une URL présignée. Il n’est plus nécessaire d’acheminer les données binaires via les processus Java AEM, ce qui accélère les chargements et réduit la charge du serveur.
Avant d’exécuter l’exemple d’application, comprenons le flux de chargement binaire direct.
Dans le flux de chargement binaire direct, les données binaires sont chargées directement dans l’espace de stockage cloud avec des URL prédéfinies. AEM as a Cloud Service assure des traitements légers, tels que la génération des URL prédéfinies et la notification de la fin du chargement au service AEM Asset Compute. Le diagramme de flux logique suivant illustre le flux de chargement binaire direct.
La bibliothèque de chargement AEM
La bibliothèque Node.js aem-upload abstrait les détails d’implémentation de l’approche chargement binaire direct. Il propose deux classes pour orchestrer le processus de chargement :
- FileSystemUpload - Utilisez-le lors du chargement de fichiers à partir du système de fichiers local, y compris la prise en charge des structures de répertoires
- DirectBinaryUpload - Utilisez-le pour un contrôle plus précis du processus de chargement binaire, comme le chargement à partir de flux ou de tampons
Exemple d’application
Utilisez l’application aem-asset-upload-sample pour découvrir le processus de chargement de ressources par programmation. L’exemple d’application illustre l’utilisation des classes FileSystemUpload et DirectBinaryUpload de la bibliothèque aem-upload.
Conditions préalables
Avant d’exécuter l’exemple d’application, vérifiez que vous disposez des conditions préalables suivantes :
- Environnement de création AEM as a Cloud Service tel que l’environnement de développement rapide (RDE), l’environnement de développement, etc.
- Node.js (dernière version du LTS)
- Compréhension de base de Node.js et npm
Télécharger l’exemple d’application
-
Téléchargez le fichier zip d’application aem-asset-upload-sample et extrayez-le.
code language-bash $ unzip aem-asset-upload-sample.zip -
Ouvrez le dossier extrait dans votre éditeur de code préféré.
code language-bash $ cd aem-asset-upload-sample $ code . -
À l’aide du terminal de l’éditeur de code, installez les dépendances.
code language-bash $ npm install
Configuration de l’exemple d’application
Avant d’exécuter l’exemple d’application, vous devez le configurer avec les détails de l’environnement AEM as a Cloud Service nécessaires tels que l’URL de création AEM, la méthode d’authentification et le chemin d’accès au dossier de ressources.
Il existe plusieurs méthodes d’authentification prises en charge par la bibliothèque Node.js aem-upload. Le tableau suivant résume les méthodes d’authentification prises en charge et leur objectif.
Pour configurer l’exemple d’application, procédez comme suit :
-
Copiez le fichier
env.exampledans.envfichier .code language-bash $ cp env.example .env -
Ouvrez le fichier
.envet mettez à jour la variable d’environnementAEM_URLavec l’URL de création AEM as a Cloud Service. -
Choisissez la méthode d’authentification parmi les options suivantes et mettez à jour les variables d’environnement correspondantes.
Pour utiliser l’authentification de base, vous devez créer un utilisateur dans l’environnement AEM as a Cloud Service.
-
Connectez-vous à votre environnement AEM as a Cloud Service.
-
Accédez à Outils > Sécurité > Utilisateurs et cliquez sur le bouton Créer.
-
Saisir les détails de l’utilisateur
-
Dans l’onglet Groupes, ajoutez le groupe Utilisateurs du DAM. Cliquez sur le bouton Enregistrer et fermer.
-
Mettez à jour les variables d’environnement
AEM_USERNAMEetAEM_PASSWORDavec le nom d’utilisateur et le mot de passe de l’utilisateur créé.
Pour obtenir le jeton de développement local, vous devez utiliser le Developer Console AEM. Le jeton généré est de type JSON Web Token (JWT) .
-
Connectez-vous à Adobe Cloud Manager et accédez à la page de détails Environnement souhaitée. Cliquez sur le bouton »… » et sélectionnez .
-
Connectez-vous à AEM Developer Console et utilisez le bouton Nouvelle console pour passer à la nouvelle console.
-
Dans la section Outils, sélectionnez Intégrations et cliquez sur le bouton Obtenir le jeton local.
-
Copiez la valeur de jeton et mettez à jour la variable d’environnement
AEM_BEARER_TOKENavec la valeur de jeton.
Notez que le jeton de développement local est valide pendant 24 heures et est émis pour l’utilisateur ou l’utilisatrice qui a généré le jeton.
Pour obtenir les informations d’identification de service, vous devez utiliser le Developer Console AEM. Il est utilisé pour générer le jeton de type JSON Web Token (JWT) à l’aide du module npm jwt-auth.
-
Connectez-vous à Adobe Cloud Manager et accédez à la page de détails Environnement souhaitée. Cliquez sur le bouton »… » et sélectionnez .
-
Connectez-vous à AEM Developer Console et utilisez le bouton Nouvelle console pour passer à la nouvelle console.
-
Dans la section Outils, sélectionnez Intégrations et cliquez sur le bouton Créer un compte technique.
-
Cliquez sur l’option Affichage pour copier le fichier JSON des informations d’identification du service.
-
Créez un fichier
service-credentials.jsonà la racine de l’exemple d’application et collez le code JSON des informations d’identification du service dans le fichier . -
Mettez à jour la variable d’environnement
AEM_SERVICE_CREDENTIALS_FILEavec le chemin d’accès au fichier service-credentials.json. -
Assurez-vous que l’utilisateur des informations d’identification du service dispose des autorisations nécessaires pour charger des ressources dans l’environnement AEM as a Cloud Service. Pour plus d’informations, voir la page Configurer l’accès dans AEM.
Voici un exemple complet de fichier .env avec les trois méthodes d’authentification configurées.
# 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
Exécuter l’exemple d’application
L’exemple d’application présente trois différentes manières de charger des exemples de ressources dans l’environnement AEM as a Cloud Service.
- FileSystemUpload - Chargez des fichiers à partir d’un système de fichiers local avec prise en charge de la structure de répertoires et création automatique de dossiers
- DirectBinaryUpload - Charge un fichier distant. Le fichier binaire est mis en mémoire tampon avant le chargement dans l’environnement AEM as a Cloud Service.
- Chargement par lots - Charge plusieurs fichiers par lots à partir d’un système de fichiers local avec une logique de reprise automatique et une récupération en cas d’erreur. En arrière-plan, il utilise la classe
FileSystemUploadpour charger des fichiers à partir du système de fichiers local.
Les ressources à charger se trouvent dans le dossier sample-assets et contiennent des sous-dossiers img, video et doc contenant chacun quelques exemples de ressources.
- Pour exécuter l’exemple d’application, utilisez la commande suivante :
$ npm start
- Saisissez l’option souhaitée numéro parmi les choix suivants :
╔════════════════════════════════════════════════════════════╗
║ 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
Les onglets suivants présentent l’exemple d’exécution d’application, sa sortie et les ressources chargées dans l’environnement AEM as a Cloud Service pour chaque méthode de chargement.
- Exemple de sortie d’application pour
FileSystemUploadoption :
| code language-bash |
|---|
|
-
Assets téléchargé à l’aide de l’option
FileSystemUploaddans l’environnement AEM as a Cloud Service :
- Exemple de sortie d’application pour
DirectBinaryUploadoption :
| code language-bash |
|---|
|
- Assets téléchargé à l’aide de l’option
DirectBinaryUploaddans l’environnement AEM as a Cloud Service :
- Exemple de sortie d’application pour
Batch Uploadoption :
| code language-bash |
|---|
|
- Assets téléchargé à l’aide de l’option
Batch Uploaddans l’environnement AEM as a Cloud Service :
Examiner l’exemple de code d’application
Le principal point d’entrée de l’exemple d’application est le fichier index.js. Il contient la fonction promptUser qui invite l’utilisateur à choisir et exécute l’exemple sélectionné.
/**
* 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();
});
}
});
}
Pour obtenir le code complet, reportez-vous au fichier index.js de l’exemple d’application.
Les onglets suivants présentent les détails d’implémentation de chaque méthode de chargement.
La classe FileSystemUpload est utilisée pour charger des fichiers à partir du système de fichiers local avec la prise en charge de la structure de répertoires et la création automatique de dossiers.
| code language-javascript |
|---|
|
Pour obtenir le code complet, reportez-vous au fichier examples/filesystem-upload.js de l’exemple d’application.
La classe DirectBinaryUpload est utilisée pour charger un fichier distant dans l’environnement AEM as a Cloud Service.
| code language-javascript |
|---|
|
Pour obtenir le code complet, reportez-vous au fichier examples/direct-binary-upload.js de l’exemple d’application.
Il divise les fichiers en lots et les charge par lots avec une logique de reprise automatique et une récupération des erreurs. En arrière-plan, il utilise la classe FileSystemUpload pour charger des fichiers à partir du système de fichiers local.
| code language-javascript |
|---|
|
Pour obtenir le code complet, reportez-vous au fichier examples/batch-upload.js de l’exemple d’application.
En outre, le fichier README.md de l’exemple d’application contient la documentation détaillée de l’exemple d’application.
Bonnes pratiques
-
Choisir la bonne méthode d’authentification :
Utilisez les informations d’identification de service pour les environnements de production, le jeton de développement local et l’authentification de base pour le développement/test uniquement. Assurez-vous que l’utilisateur des informations d’identification du service dispose des autorisations nécessaires pour charger des ressources dans l’environnement AEM as a Cloud Service. -
Choisir la bonne méthode de chargement :
Utilisez FileSystemUpload pour les fichiers locaux avec création de dossiers automatique, DirectBinaryUpload pour les flux/tampons/URL distantes avec contrôle précis et Modèle de chargement par lots pour les environnements de production avec plus de 1 000 fichiers nécessitant une logique de reprise. -
Structure correcte des objets de fichier DirectBinaryUpload
Utilisez la propriété blob (et non la mémoire tampon) avec les champs obligatoires : { fileName, fileSize, blob: buffer, targetFolder } et souvenez-vous que DirectBinaryUpload ne crée PAS automatiquement de dossiers. -
Exemple d’application comme référence :
L’exemple d’application est une bonne référence pour les détails d’implémentation du processus de chargement de ressources de la programmation. Vous pouvez l’utiliser comme point de départ pour votre propre mise en œuvre.