Desarrollo de una aplicación personalizada

Antes de comenzar a desarrollar una aplicación personalizada:

Crear una aplicación personalizada

Asegúrese de tener la variable Adobe I/O CLI instalado localmente.

  1. Para crear una aplicación personalizada, crear un proyecto de App Builder. Para ello, ejecute aio app init <app-name> en su terminal.

    Si aún no ha iniciado sesión, este comando le pide a un navegador que le pida que inicie sesión en la Consola de Adobe Developer con su Adobe ID. Consulte here para obtener más información sobre cómo iniciar sesión desde el cli.

    Adobe recomienda iniciar sesión. Si tiene problemas, siga las instrucciones para crear una aplicación sin iniciar sesión.

  2. Después de iniciar sesión, siga las indicaciones de la CLI y seleccione la Organization, Projecty Workspace para usar en la aplicación. Elija el proyecto y el espacio de trabajo que creó al configurar el entorno. Cuando se Which extension point(s) do you wish to implement ?, asegúrese de seleccionar DX Asset Compute Worker:

    $ aio app init <app-name>
    Retrieving information from Adobe I/O Console.
    ? Select Org My Adobe Org
    ? Select Project MyFireflyProject
    ? Which extension point(s) do you wish to implement ? (Press <space> to select, <a>
    to toggle all, <i> to invert selection)
    ❯◯ DX Experience Cloud SPA
    ◯ DX Asset Compute Worker
    
  3. Cuando se le solicita Which Adobe I/O App features do you want to enable for this project?, seleccione Actions. Asegúrese de anular la selección Web Assets como recursos web utilizan distintas comprobaciones de autenticación y autorización.

    ? 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. Cuando se Which type of sample actions do you want to create?, asegúrese de seleccionar 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. Siga el resto de las indicaciones y abra la nueva aplicación en Visual Studio Code (o su editor de código favorito). Contiene el scaffolding y el código de ejemplo para una aplicación personalizada.

    Lea aquí sobre componentes principales de una aplicación de App Builder.

    La aplicación de plantilla aprovecha nuestra SDK de asset compute para la carga, descarga y organización de representaciones de aplicaciones, de modo que los desarrolladores solo tengan que implementar la lógica de aplicación personalizada. Dentro de actions/<worker-name> carpeta, index.js es donde se agrega el código de aplicación personalizado.

Consulte ejemplos de aplicaciones personalizadas para ver ejemplos e ideas para aplicaciones personalizadas.

Agregar credenciales

Cuando inicia sesión al crear la aplicación, la mayoría de las credenciales de App Builder se recopilan en el archivo ENV. Sin embargo, el uso de la herramienta para desarrolladores requiere credenciales adicionales.

Credenciales de almacenamiento de herramientas para desarrolladores

La herramienta para desarrolladores utilizada para probar aplicaciones personalizadas con el Asset Compute service requiere un contenedor de almacenamiento en la nube para alojar archivos de prueba y para recibir y mostrar representaciones generadas por aplicaciones.

NOTA

Esto es independiente del almacenamiento en la nube de Adobe Experience Manager como Cloud Service. Solo se aplica para desarrollar y probar con la herramienta para desarrolladores de Asset compute.

Asegúrese de tener acceso a un contenedor de almacenamiento en la nube admitido. Este contenedor lo pueden compartir varios desarrolladores entre diferentes proyectos según sea necesario.

Agregar credenciales al archivo ENV

Agregue las siguientes credenciales para la herramienta de desarrollo al archivo ENV en la raíz del proyecto de App Builder:

  1. Añada la ruta absoluta al archivo de clave privada creado al agregar servicios al proyecto de App Builder:

    ASSET_COMPUTE_PRIVATE_KEY_FILE_PATH=
    
  2. Descargue el archivo desde la consola de Adobe Developer. Vaya a la raíz del proyecto y haga clic en Descargar todo en la esquina superior derecha. El archivo se descarga con <namespace>-<workspace>.json como nombre de archivo. Realice una de las acciones siguientes:

    • Cambie el nombre del archivo como console.json y muévalo a la raíz del proyecto.

    • De forma opcional, puede agregar la ruta absoluta al archivo JSON de integración de la consola de Adobe Developer. Esto es igual console.json que se descarga en el espacio de trabajo del proyecto.

      ASSET_COMPUTE_INTEGRATION_FILE_PATH=
      
  3. Agregue las credenciales de almacenamiento de S3 o Azure. Solo necesita acceder a una solución de almacenamiento en la nube.

    # 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=
    
SUGERENCIA

La variable config.json contiene credenciales. Desde su proyecto, agregue el archivo JSON a su .gitignore para evitar que se comparta. Lo mismo se aplica a los archivos .env y .aio.

Ejecución de la aplicación

Antes de ejecutar la aplicación con la herramienta para desarrolladores de Asset compute, configure correctamente la variable credenciales.

Para ejecutar la aplicación en la herramienta para desarrolladores, utilice aio app run comando. Implementa la acción en Adobe I/O Ejecución e inicie la herramienta de desarrollo en su equipo local. Esta herramienta se utiliza para probar las solicitudes de aplicación durante el desarrollo. A continuación se muestra un ejemplo de solicitud de representación:

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

No use el --local con la variable run comando. No funciona con Asset Compute aplicaciones personalizadas y la herramienta para desarrolladores de Asset compute. Las aplicaciones personalizadas reciben llamadas del Asset Compute Service que no pueden acceder a las acciones que se ejecutan en los equipos locales del desarrollador.

Consulte here cómo probar y depurar la aplicación. Cuando haya terminado de desarrollar la aplicación personalizada, implementar su aplicación personalizada.

Pruebe la aplicación de ejemplo proporcionada por el Adobe

A continuación se muestran ejemplos de aplicaciones personalizadas:

Aplicación personalizada de plantilla

La variable secundario es una aplicación de plantilla. Genera una representación simplemente copiando el archivo de origen. El contenido de esta aplicación es la plantilla recibida al elegir Adobe Asset Compute en la creación de la aplicación aio.

El archivo de aplicación, worker-basic.js utiliza la variable asset-compute-sdk para descargar el archivo de origen, orqueste cada procesamiento de representación y vuelva a cargar las representaciones resultantes en el almacenamiento en la nube.

La variable renditionCallback definida dentro del código de la aplicación, es donde se realiza toda la lógica de procesamiento de la aplicación. La llamada de retorno de representación en worker-basic simplemente copia el contenido del archivo de origen en el archivo de representación.

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);
});

Llamar a una API externa

En el código de la aplicación, puede realizar llamadas de API externas para ayudar en el procesamiento de la aplicación. A continuación se muestra un archivo de aplicación de ejemplo que invoca una API externa.

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

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

Por ejemplo, la variable worker-animal-pictures realiza una solicitud de recuperación a una URL estática de Wikimedia utilizando la variable node-httptransfer biblioteca.

Pasar parámetros personalizados

Puede pasar parámetros definidos personalizados a través de los objetos de representación. Se puede hacer referencia a ellas dentro de la aplicación en rendition instrucciones. Un ejemplo de objeto de representación es:

"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"
    }
]

Un ejemplo de archivo de aplicación que accede a un parámetro personalizado es:

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"`
});

La variable example-worker-animal-pictures pasa un parámetro personalizado animal para determinar qué archivo se recuperará de Wikimedia.

Compatibilidad con autenticación y autorización

De forma predeterminada, las aplicaciones personalizadas de Asset compute incluyen comprobaciones de autorización y autenticación para el proyecto de App Builder. Esto se habilita configurando la variable require-adobe-auth anotación a true en el manifest.yml.

Acceso a otras API de Adobe

Añadir los servicios de API a la variable Asset Compute Espacio de trabajo de consola creado en la configuración. Estos servicios forman parte del token de acceso JWT generado por Asset Compute Service. Se puede acceder al token y a otras credenciales dentro de la acción de la aplicación params objeto.

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

Pasar credenciales para sistemas de terceros

Para gestionar las credenciales de otros servicios externos, pase estos como parámetros predeterminados en las acciones. Estos se cifran automáticamente en tránsito. Para obtener más información, consulte creación de acciones en la guía para desarrolladores de Runtime. A continuación, configúrelos mediante variables de entorno durante la implementación. Se puede acceder a estos parámetros en la params dentro de la acción.

Establezca los parámetros predeterminados dentro de la variable inputs en el manifest.yml:

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

La variable $VAR expresión lee el valor de una variable de entorno denominada VAR.

Durante el desarrollo, el valor se puede configurar en el archivo ENV local como aio lee automáticamente las variables de entorno de los archivos ENV además de las variables configuradas desde el shell de invocación. En este ejemplo, el archivo ENV tiene el siguiente aspecto:

#...
SECRET_KEY=secret-value

Para la implementación de producción, se pueden configurar las variables de entorno en el sistema CI, por ejemplo, utilizando secretos en las acciones de GitHub. Por último, acceda a los parámetros predeterminados dentro de la aplicación como estos:

const key = params.secretKey;

Cambio de tamaño de aplicaciones

Una aplicación se ejecuta en un contenedor de Adobe I/O Tiempo de ejecución con límites que se puede configurar mediante el manifest.yml:

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

Debido al procesamiento más extenso que suelen realizar las aplicaciones de Asset compute, es más probable que uno tenga que ajustar estos límites para obtener un rendimiento óptimo (lo suficientemente grande como para gestionar recursos binarios) y eficacia (no malgastar recursos debido a la memoria contenedora no utilizada).

El tiempo de espera predeterminado para las acciones en tiempo de ejecución es de un minuto, pero se puede aumentar estableciendo la variable timeout límite (en milisegundos). Si espera procesar archivos más grandes, incremente esta vez. Tenga en cuenta el tiempo total que se tarda en descargar el origen, procesar el archivo y cargar la representación. Si se agota el tiempo de espera de una acción, es decir, no devuelve la activación antes del límite de tiempo de espera especificado, Runtime descarta el contenedor y no lo vuelve a utilizar.

Por naturaleza, las aplicaciones de asset compute tienden a estar conectadas a la red y al disco de entrada o salida. El archivo de origen debe descargarse primero, el procesamiento suele requerir muchos recursos y, a continuación, las representaciones resultantes se cargan de nuevo.

La memoria disponible para un contenedor de acciones la especifica memorySize en MB. Actualmente, esto también define cuánto acceso de CPU obtiene el contenedor y, lo más importante, es un elemento clave del coste de uso del tiempo de ejecución (los contenedores más grandes cuestan más). Utilice aquí un valor mayor cuando el procesamiento requiera más memoria o CPU, pero tenga cuidado de no desperdiciar recursos, ya que cuanto más grandes sean los contenedores, menor será el rendimiento general.

Además, es posible controlar la concurrencia de acciones dentro de un contenedor mediante el concurrency configuración. Este es el número de activaciones simultáneas que obtiene un solo contenedor (de la misma acción). En este modelo, el contenedor de acciones es como un servidor Node.js que recibe varias solicitudes simultáneas, hasta ese límite. Si no se establece, el valor predeterminado en Tiempo de ejecución es 200, que es bueno para las acciones más pequeñas de App Builder, pero normalmente es demasiado grande para las aplicaciones de Asset compute, dado que su procesamiento local y actividad de disco son más intensos. Algunas aplicaciones, dependiendo de su implementación, también podrían no funcionar bien con la actividad concurrente. El SDK de Asset compute garantiza que las activaciones se separen escribiendo archivos en distintas carpetas únicas.

Probar aplicaciones para encontrar los números óptimos para concurrency y memorySize. Contenedores más grandes = un límite de memoria más alto podría permitir más concurrencia, pero también podría ser derrochador para tráfico más bajo.

En esta página