Développement d’une application personnalisée

Avant de commencer à développer une application personnalisée :

Création d’une application personnalisée

Assurez-vous que l’interface en ligne de commande Adobe I/O est installée localement.

  1. Pour créer une application personnalisée, créez une application Firefly. Pour ce faire, exécutez aio app init <app-name> sur votre terminal.

    Si vous n’êtes pas encore connecté, cette commande appelle un navigateur qui vous invite à vous connecter à Adobe Developer Console avec votre Adobe ID. Voir ici pour plus d’informations sur la connexion à partir de l’interface de ligne de commande.

    Adobe vous recommande de vous connecter. Si vous rencontrez des problèmes, appliquez les instructions pour créer une application sans vous connecter.

  2. Après vous être connecté, suivez les invites de l’interface en ligne de commande et sélectionnez les éléments Organization, Project et Workspace à utiliser pour l’application. Choisissez le projet et l’espace de travail que vous avez créés lors de la configuration de votre environnement.

    $ aio app init <app-name>
    Retrieving information from [!DNL Adobe I/O] Console.
    ? Select Org My Adobe Org
    ? Select Project MyFireflyProject
    ? Select Workspace myworkspace
    create console.json
    
  3. Lorsque l’invite Which Adobe I/O App features do you want to enable for this project? s’affiche, sélectionnez Actions. Veillez à désélectionner l’option Web Assets car les ressources Web utilisent différentes vérifications d’authentification et d’autorisation.

    ? Which Adobe I/O App features do you want to enable for this project?
    select components to include (Press <space> to select, <a> to toggle all, <i> to invert selection)
    ❯◉ Actions: Deploy Runtime actions
    ◯ Events: Publish to Adobe I/O Events
    ◯ Web Assets: Deploy hosted static assets
    ◯ CI/CD: Include GitHub Actions based workflows for Build, Test and Deploy
    
  4. À l’invite Which type of sample actions do you want to create?, veillez à sélectionner Adobe Asset Compute Worker :

    ? Which type of sample actions do you want to create?
    Select type of actions to generate
    ❯◉ Adobe Asset Compute Worker
    ◯ Generic
    
  5. Suivez les autres invites et ouvrez la nouvelle application dans Visual Studio Code (ou votre éditeur de code préféré). Il contient la structure et l’exemple de code pour une application personnalisée.

    Lisez ici les principaux composants d’une application Firefly.

    L’application de modèle utilise notre SDK Asset Compute pour le chargement, le téléchargement et l’orchestration des rendus d’application. Les développeurs n’ont donc qu’à implémenter la logique de l’application personnalisée. Dans le dossier actions/<worker-name>, le fichier index.js indique où ajouter le code d’application personnalisé.

Voir Exemples d’applications personnalisées pour consulter des exemples et des idées d’applications personnalisées.

Ajout des informations d’identification

Lorsque vous vous connectez lors de la création de l’application, la plupart des informations d’identification de Firefly sont collectées dans votre fichier ENV. Toutefois, l’utilisation de l’outil de développement nécessite des informations d’identification supplémentaires.

Informations d’identification pour le stockage de l’outil de développement

L’outil de développement utilisé pour tester les applications personnalisées avec Asset Compute service nécessite un conteneur de stockage dans le cloud pour l’hébergement des fichiers de test, ainsi que la réception et l’affichage des rendus générés par les applications.

REMARQUE

Il est distinct de l’espace de stockage dans le cloud d’Adobe Experience Manager as a Cloud Service. Il s’applique uniquement au développement et au test avec l’outil de développement Asset Compute.

Assurez-vous d’avoir accès à un conteneur de stockage dans le cloud pris en charge. Ce conteneur peut être partagé par plusieurs développeurs sur différents projets, selon les besoins.

Ajout des informations d’identification au fichier ENV

Ajoutez les informations d’identification suivantes pour l’outil de développement dans le fichier ENV dans la racine de votre projet Firefly :

  1. Ajoutez le chemin d’accès absolu au fichier de clé privée créé lors de l’ajout de services à votre projet Firefly :

    ASSET_COMPUTE_PRIVATE_KEY_FILE_PATH=
    
  2. Téléchargez le fichier à partir d’Adobe Developer Console. Accédez à la racine du projet et cliquez sur « Tout télécharger » dans l’angle supérieur droit. Le fichier est téléchargé avec <namespace>-<workspace>.json comme nom de fichier. Utilisez l’une des méthodes suivantes :

    • Renommez le fichier config.json et déplacez-le dans la racine de votre projet.

    • Vous pouvez éventuellement ajouter le chemin d’accès absolu au fichier JSON d’intégration d’Adobe Developer Console. Il s’agit du même fichier console.json que celui téléchargé dans l’espace de travail du projet.

      ASSET_COMPUTE_INTEGRATION_FILE_PATH=
      
  3. Ajoutez les informations d’identification S3 ou de la solution de stockage Azure. Vous n’avez besoin d’accéder qu’à une seule solution d’espace de stockage dans le cloud.

    # S3 credentials
    S3_BUCKET=
    AWS_ACCESS_KEY_ID=
    AWS_SECRET_ACCESS_KEY=
    AWS_REGION=
    
    # Azure Storage credentials
    AZURE_STORAGE_ACCOUNT=
    AZURE_STORAGE_KEY=
    AZURE_STORAGE_CONTAINER_NAME=
    
CONSEIL

Le fichier config.json contient des informations d’identification. Dans votre projet, ajoutez le fichier JSON à votre fichier .gitignore pour empêcher son partage. Il en va de même pour les fichiers .env et .aio.

Exécution de l’application

Avant d’exécuter l’application avec l’outil de développement Asset Compute, configurez correctement les informations d’identification.

Pour exécuter l’application dans l’outil de développement, utilisez la commande aio app run. L’action est déployée sur Runtime Adobe I/O et lance l’outil de développement sur votre machine locale. Cet outil est utilisé pour tester les demandes des applications au cours du développement. Voici un exemple de demande de rendu :

"renditions": [
    {
        "worker": "https://1234_my_namespace.adobeioruntime.net/api/v1/web/example-custom-worker-master/worker",
        "name": "image.jpg"
    }
]
REMARQUE

N’utilisez pas l’indicateur --local avec la commande run. Il ne fonctionne pas avec les applications personnalisées Asset Compute et l’outil de développement Asset Compute. Les applications personnalisées sont appelées par Asset Compute Service qui ne peut pas accéder aux actions exécutées sur les machines locales des développeurs.

Voir ici comment tester et déboguer votre application. Lorsque vous avez terminé de développer votre application personnalisée, déployez-la.

Essai de l’exemple d’application fourni par Adobe

Voici des exemples d’applications personnalisées :

Modèle d’application personnalisée

worker-basic est un modèle d’application. Il génère un rendu en copiant simplement le fichier source. Le contenu de cette application est le modèle reçu lors du choix d’Adobe Asset Compute lors de la création de l’application aio.

Le fichier de l’application worker-basic.js utilise le asset-compute-sdk pour télécharger le fichier source, orchestrer le traitement de chaque rendu et charger les rendus résultants dans l’espace de stockage dans le cloud.

Le renditionCallback défini dans le code de l’application, permet d’exécuter toute la logique de traitement de l’application. Le rappel de rendu de worker-basic copie simplement le contenu du fichier source dans le fichier de rendu.

const { worker } = require('@adobe/asset-compute-sdk');
const fs = require('fs').promises;

exports.main = worker(async (source, rendition) => {
    // copy source to rendition to transfer 1:1
    await fs.copyFile(source.path, rendition.path);
});

Appel d’une API externe

Dans le code de l’application, vous pouvez effectuer des appels d’API externe pour faciliter le traitement de l’application. Vous trouverez ci-dessous un exemple de fichier d’application appelant une API externe.

exports.main = worker(async function (source, rendition) {

    const response = await fetch('https://adobe.com', {
        method: 'GET',
        Authorization: params.AUTH_KEY
    })
});

Par exemple, worker-animal-pictures effectue une requête de récupération d’une URL statique à partir de Wikimedia à l’aide de la bibliothèque node-httptransfer.

Transmission de paramètres personnalisés

Vous pouvez transmettre des paramètres personnalisés définis à l’aide des objets de rendu. Ils peuvent être référencés dans l’application au moyen d’renditioninstructions. Voici un exemple d’objet de rendu :

"renditions": [
    {
        "worker": "https://1234_my_namespace.adobeioruntime.net/api/v1/web/example-custom-worker-master/worker",
        "name": "image.jpg",
        "my-custom-parameter": "my-custom-parameter-value"
    }
]

Voici un exemple de fichier d’application accédant à un paramètre personnalisé :

exports.main = worker(async function (source, rendition) {

    const customParam = rendition.instructions['my-custom-parameter'];
    console.log('Custom paramter:', customParam);
    // should print out `Custom parameter: "my-custom-parameter-value"`
});

example-worker-animal-pictures transmet un paramètre personnalisé animal pour déterminer le fichier à récupérer auprès de Wikimedia.

Prise en charge de l’authentification et de l’autorisation

Par défaut, les applications personnalisées Asset Compute sont fournies avec des contrôles d’autorisation et d’authentification pour les applications Firefly. Cette fonction est activée en définissant l’annotation require-adobe-auth sur true dans manifest.yml.

Accès à d’autres API d’Adobe

Ajoutez les services d’API à l’espace de travail de la console Asset Compute créé lors de la configuration. Ces services font partie du jeton d’accès JWT généré par Asset Compute Service. Le jeton et les autres informations d’identification sont accessibles dans l’objet params d’action de l’application.

const accessToken = params.auth.accessToken; // JWT token for Technical Account with entitlements from the console workspace to the API service
const clientId = params.auth.clientId; // Technical Account client Id
const orgId = params.auth.orgId; // Experience Cloud Organization

Transmission des informations d’identification des systèmes tiers

Pour gérer les informations d’identification d’autres services externes, transmettez-les sous la forme de paramètres par défaut sur les actions. Ils sont automatiquement chiffrés en transit. Pour plus d’informations, voir Création d’actions dans le guide du développeur Runtime. Définissez-les ensuite à l’aide de variables d’environnement lors du déploiement. Ces paramètres sont accessibles dans l’objet params à l’intérieur de l’action.

Définissez les paramètres par défaut dans inputs dans le fichier manifest.yml :

packages:
  __APP_PACKAGE__:
    actions:
      worker:
        function: 'index.js'
        runtime: 'nodejs:10'
        web: true
        inputs:
           secretKey: $SECRET_KEY
        annotations:
          require-adobe-auth: true

L’expression $VAR lit la valeur d’une variable d’environnement nommée VAR.

Au cours du développement, la valeur peut être définie dans le fichier ENV local, car aio lit automatiquement les variables d’environnement des fichiers ENV en plus de celles définies dans le shell appelant. Dans cet exemple, le fichier ENV ressemble à ce qui suit :

#...
SECRET_KEY=secret-value

Pour le déploiement de la production, il est possible de définir les variables d’environnement dans le système d’intégration continue (CI), par exemple en utilisant des secrets dans les actions GitHub. Enfin, accédez aux paramètres par défaut de l’application en tant que tels :

const key = params.secretKey;

Dimensionnement des applications

Une application s’exécute dans un conteneur Runtime Adobe I/O avec des limites configurables à l’aide de manifest.yml :

    actions:
      myworker:
        function: /actions/myworker/index.js
        limits:
          timeout: 300000
          memorySize: 512
          concurrency: 1

En raison du traitement plus étendu généralement effectué par les applications Asset Compute, il est plus probable qu’il y ait à ajuster ces limites pour optimiser les performances (suffisamment pour gérer les ressources binaires) et l’efficacité (sans gaspiller les ressources en raison de la mémoire de conteneur inutilisée).

Le délai d’expiration par défaut pour les actions du Runtime est d’une minute, mais il peut être augmenté en définissant la limite timeout (en millisecondes). Si vous prévoyez de traiter des fichiers plus volumineux, augmentez cette durée. Tenez compte du temps total nécessaire pour télécharger la source, traiter le fichier et charger le rendu. Si une action atteint le délai d’expiration, c’est-à-dire si elle ne renvoie pas l’activation avant la limite de délai spécifiée, le Runtime ignore le conteneur et ne le réutilise pas.

Les applications Asset Compute tendent par nature à être liées aux entrées et sorties réseau et disque. Le fichier source doit d’abord être téléchargé (le traitement est souvent lourd en termes de ressource) et les rendus résultants sont ensuite chargés à nouveau.

La mémoire disponible pour un conteneur d’action est spécifiée par le paramètre memorySize en Mo. Actuellement, il définit également le niveau d’accès du conteneur à l’unité centrale. Il s’agit surtout d’un élément clé du coût d’utilisation du Runtime (les conteneurs plus volumineux coûtent plus cher). Utilisez ici une valeur plus élevée lorsque votre traitement nécessite davantage de mémoire ou d’unité centrale. Veillez toutefois à ne pas gaspiller les ressources, car plus les conteneurs sont volumineux, plus le débit global est faible.

En outre, il est possible de contrôler la simultanéité des actions dans un conteneur à l’aide du paramètre concurrency. Il s’agit du nombre d’activations simultanées obtenues par un seul conteneur (de la même action). Dans ce modèle, le conteneur d’action est semblable à un serveur Node.js recevant plusieurs requêtes simultanées, jusqu’à cette limite. Si elle n’est pas définie, la valeur par défaut dans le Runtime est de 200, ce qui est idéal pour les actions Firefly plus modestes, mais généralement trop élevé pour les applications Asset Compute, compte tenu de l’intensité accrue des activités de disque et des traitements locaux. Selon leur mise en œuvre, il est possible que certaines applications ne fonctionnent pas correctement avec les activités simultanées. Le SDK Asset Compute garantit que les activations sont séparées en écrivant des fichiers dans différents dossiers uniques.

Testez les applications pour trouver les valeurs optimales de concurrency et memorySize. Des conteneurs plus volumineux reviennent à une limite de mémoire plus haute, ce qui permet une plus grande simultanéité, mais peut aussi entraîner du gaspillage si le trafic est plus faible.

Sur cette page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free