Desarrollar una aplicación personalizada develop

Antes de empezar a desarrollar una aplicación personalizada:

Creación de una aplicación personalizada create-custom-application

Asegúrese de tener Adobe aio-cli instalado localmente.

  1. Para crear una aplicación personalizada, cree 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 solicitará al explorador que inicie sesión en Adobe Developer Console con su Adobe ID. Vea aquí para obtener más información sobre cómo iniciar sesión desde el cli.

    El Adobe recomienda que inicie sesión primero. 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 Organization, Project y Workspace para usar en la aplicación. Elija el proyecto y el área de trabajo que creó al configurar su entorno. Cuando se le solicite Which extension point(s) do you wish to implement ?, asegúrese de seleccionar DX Asset Compute Worker:

    code language-sh
    $ aio app init <app-name>
    Retrieving information from Adobe I/O Console.
    ? Select Org My Adobe Org
    ? Select Project MyAdobe Developer App BuilderProject
    ? 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 pregunte Which Adobe I/O App features do you want to enable for this project?, seleccione Actions. Asegúrese de anular la selección de la opción Web Assets, ya que los recursos web utilizan comprobaciones de autenticación y autorización diferentes.

    code language-bash
    ? 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 le solicite Which type of sample actions do you want to create?, asegúrese de seleccionar Adobe Asset Compute Worker:

    code language-bash
    ? 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 andamiaje y el código de ejemplo de una aplicación personalizada.

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

    La aplicación de plantillas aprovecha el SDK de Asset compute de Adobe para cargar, descargar y organizar representaciones de aplicaciones, de modo que los desarrolladores solo necesitan implementar la lógica de aplicación personalizada. Dentro de la carpeta actions/<worker-name>, el archivo index.js es donde se agrega el código de aplicación personalizado.

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

Añadir credenciales add-credentials

Al iniciar 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 developer-tool-credentials

La herramienta para que los desarrolladores evalúen las aplicaciones personalizadas que usan Asset Compute service necesita el uso de un contenedor de almacenamiento en la nube. Este contenedor es esencial para almacenar los archivos de prueba y para la recepción y presentación de las representaciones producidas por las aplicaciones.

NOTE
Este contenedor es independiente del almacenamiento en la nube de Adobe Experience Manager como Cloud Service. Solo se aplica al desarrollo y las pruebas con la herramienta para desarrolladores de Assets computes.

Asegúrese de tener acceso a un contenedor de almacenamiento en la nube compatible. Varios desarrolladores utilizan este contenedor de forma colectiva para diferentes proyectos siempre que es necesario.

Agregar credenciales al archivo ENV add-credentials-env-file

Inserte las credenciales subsiguientes para la herramienta de desarrollo en el archivo .env. El archivo se encuentra en la raíz del proyecto de App Builder:

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

    code language-conf
    ASSET_COMPUTE_PRIVATE_KEY_FILE_PATH=
    
  2. Descargue el archivo desde Adobe Developer Console. 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 siguientes acciones:

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

    • De forma opcional, puede añadir la ruta absoluta al archivo JSON de integración de Adobe Developer Console. Este archivo es el mismo archivo console.json que se descargó en el área de trabajo del proyecto.

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

    code language-conf
    # 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=
    
TIP
El archivo config.json contiene credenciales. Desde el proyecto, agregue el archivo JSON al archivo .gitignore para evitar que se comparta. Lo mismo se aplica a .env y .aio archivos.

Ejecución de la aplicación run-custom-application

Antes de ejecutar la aplicación con la herramienta para desarrolladores de Assets computes, configure correctamente credentials.

Para ejecutar la aplicación en la herramienta para desarrolladores, utilice el comando aio app run. Implementa la acción en el Adobe I/O Runtime e inicia la herramienta de desarrollo en el equipo local. Esta herramienta se utiliza para probar las solicitudes de aplicación durante el desarrollo. Este es 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"
    }
]
NOTE
No use el marcador --local con el comando run. No funciona con Asset Compute aplicaciones personalizadas ni con la herramienta para desarrolladores de Assets computes. El servicio Asset Compute llama a las aplicaciones personalizadas y no puede tener acceso a las acciones que se ejecutan en los equipos locales del desarrollador.

Vea aquí cómo probar y depurar su aplicación. Cuando haya terminado de desarrollar su aplicación personalizada, implemente su aplicación personalizada.

Pruebe la aplicación de ejemplo proporcionada por Adobe. try-sample

A continuación se muestran ejemplos de aplicaciones personalizadas:

Aplicación personalizada de plantilla template-custom-application

worker-basic 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 usa asset-compute-sdk para descargar el archivo de origen, organizar cada procesamiento de representación y cargar las representaciones resultantes de nuevo en el almacenamiento de la nube.

El renditionCallback definido dentro del código de aplicación es donde se debe realizar toda la lógica de procesamiento de la aplicación. La llamada de retorno de representación de 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 call-external-api

En el código de la aplicación, puede realizar llamadas de API externas para ayudar con el procesamiento de la aplicación. A continuación encontrará 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, worker-animal-pictures realiza una solicitud de captura a una dirección URL estática desde Wikimedia usando la biblioteca node-httptransfer.

Pasar parámetros personalizados pass-custom-parameters

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

"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 tiene acceso a un parámetro personalizado es el siguiente:

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 pasa un parámetro personalizado animal para determinar qué archivo se va a obtener de Wikimedia.

Compatibilidad con autenticación y autorización authentication-authorization-support

De forma predeterminada, las aplicaciones personalizadas de Asset Compute incluyen comprobaciones de autorización y autenticación para el proyecto de App Builder. Se habilitó al establecer la anotación require-adobe-auth en true en manifest.yml.

Acceso a otras API de Adobe access-adobe-apis

Agregue los servicios API al área de trabajo de la consola Asset Compute creada durante la instalació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 del objeto de acción params de la aplicación.

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 pass-credentials-for-tp

Para gestionar las credenciales de otros servicios externos, páselas como parámetros predeterminados en las acciones. 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 Adobe I/O Runtime. A continuación, configúrelos mediante variables de entorno durante la implementación. Se puede tener acceso a estos parámetros en el objeto params dentro de la acción.

Establecer los parámetros predeterminados dentro de inputs en 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 expresión $VAR lee el valor de una variable de entorno denominada VAR.

Al desarrollar, puede asignar el valor en el archivo .env local. El motivo es que aio importa automáticamente variables de entorno de .env archivos, junto con las variables establecidas por el shell iniciador. En este ejemplo, el archivo .env tiene el siguiente aspecto:

#...
SECRET_KEY=secret-value

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

const key = params.secretKey;

Tamaño de aplicaciones sizing-workers

Se ejecuta una aplicación en un contenedor del Adobe I/O Runtime con límites que se pueden configurar a través de manifest.yml:

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

Debido al amplio procesamiento realizado por las aplicaciones de Asset compute, debe ajustar estos límites para obtener un rendimiento óptimo (lo suficientemente grande como para gestionar recursos binarios) y una mayor eficacia (sin desperdiciar 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 el límite de timeout (en milisegundos). Si espera procesar archivos más grandes, aumente este tiempo. Considere el tiempo total que 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 se devuelve la activación antes del límite de tiempo de espera especificado, Runtime descarta el contenedor y no lo vuelve a utilizar.

Las aplicaciones de asset compute por naturaleza tienden a estar enlazadas a la red y a la entrada o salida del disco. El archivo de origen debe descargarse primero. El procesamiento suele consumir muchos recursos y, a continuación, las representaciones resultantes se cargan de nuevo.

Puede especificar la memoria asignada a un contenedor de acciones en megabytes mediante el parámetro memorySize. Actualmente, este parámetro también define cuánto acceso de CPU obtiene el contenedor y, lo que es más importante, es un elemento clave del coste de utilizar Runtime (los contenedores más grandes cuestan más). Utilice un valor mayor aquí 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 la configuración concurrency. Esta configuración 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. El valor predeterminado memorySize en tiempo de ejecución se establece en 200 MB, lo que resulta ideal para acciones de App Builder más pequeñas. En el caso de las aplicaciones de Asset compute, este valor predeterminado puede ser excesivo debido a que utilizan más recursos de disco y procesamiento local. Según su implementación, es posible que algunas aplicaciones no funcionen bien con la actividad simultánea. El SDK de Asset Compute garantiza que las activaciones estén separadas por la escritura de archivos en diferentes carpetas únicas.

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

recommendation-more-help
b027be24-3772-44c0-a56d-a4ba23dcb50b