Sviluppare un’applicazione personalizzata develop

Prima di iniziare a sviluppare un’applicazione personalizzata:

Creare un’applicazione personalizzata create-custom-application

Assicurarsi che Adobe aio-cli sia installato localmente.

Consulta esempi di applicazioni personalizzate per esempi e idee per applicazioni personalizzate.

Aggiungi credenziali add-credentials

Quando effettui l’accesso durante la creazione dell’applicazione, la maggior parte delle credenziali di App Builder viene raccolta nel file ENV. Tuttavia, l’utilizzo dello strumento per sviluppatori richiede credenziali aggiuntive.

Credenziali di archiviazione dello strumento per sviluppatori developer-tool-credentials

Lo strumento per gli sviluppatori per valutare le app personalizzate utilizzando Asset Compute service richiede l'utilizzo di un contenitore di archiviazione cloud. Questo contenitore è essenziale per memorizzare i file di test e per la ricezione e la presentazione delle rappresentazioni prodotte dalle app.

Assicurati di avere accesso a un contenitore di archiviazione cloud supportato. Questo contenitore viene utilizzato collettivamente da vari sviluppatori per progetti diversi, quando necessario.

Aggiungi credenziali al file ENV add-credentials-env-file

Inserire le credenziali successive per lo strumento di sviluppo nel file .env. Il file si trova nella directory principale del progetto App Builder:

Eseguire l’applicazione run-custom-application

Prima di eseguire l'applicazione con lo strumento per sviluppatori Asset Compute, configurare correttamente le credenziali.

Per eseguire l'applicazione nello strumento per sviluppatori, utilizzare il comando aio app run. Distribuisce l'azione all'Adobe I/O Runtime e avvia lo strumento di sviluppo nel computer locale. Questo strumento viene utilizzato per testare le richieste dell’applicazione durante lo sviluppo. Di seguito è riportato un esempio di richiesta di rappresentazione:

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

Consulta qui come testare ed eseguire il debug dell'applicazione. Al termine dello sviluppo dell'applicazione personalizzata, distribuire l'applicazione personalizzata.

Prova l’applicazione di esempio fornita da Adobe try-sample

Di seguito sono riportati alcuni esempi di applicazioni personalizzate:

Applicazione personalizzata modello template-custom-application

worker-basic è un'applicazione modello. Genera una copia trasformata semplicemente copiando il file di origine. Il contenuto di questa applicazione è il modello ricevuto quando si sceglie Adobe Asset Compute nella creazione dell'app aio.

Il file dell'applicazione worker-basic.js utilizza asset-compute-sdk per scaricare il file di origine, orchestrare ogni elaborazione della copia trasformata e caricare di nuovo le copie trasformate risultanti nell'archivio cloud.

Il renditionCallback definito nel codice dell'applicazione è il punto in cui eseguire tutta la logica di elaborazione dell'applicazione. Il callback della copia trasformata in worker-basic copia semplicemente il contenuto del file di origine nel file della copia trasformata.

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

Chiamare un’API esterna call-external-api

Nel codice dell’applicazione, puoi effettuare chiamate API esterne per facilitare l’elaborazione dell’applicazione. Di seguito è riportato un esempio di file di applicazione che richiama un’API esterna.

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

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

Ad esempio, worker-animal-pictures effettua una richiesta di recupero a un URL statico da Wikimedia utilizzando la libreria node-httptransfer.

Trasmettere i parametri personalizzati pass-custom-parameters

Potete trasmettere parametri definiti personalizzati attraverso gli oggetti di rendering. È possibile farvi riferimento all'interno dell'applicazione nelle rendition istruzioni. Un esempio di oggetto di rendering è:

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

Di seguito è riportato un esempio di file di applicazione che accede a un parametro personalizzato:

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 trasmette un parametro personalizzato animal per determinare quale file recuperare da Wikimedia.

Supporto di autenticazione e autorizzazione authentication-authorization-support

Per impostazione predefinita, le applicazioni personalizzate di Asset compute sono fornite con i controlli di autorizzazione e autenticazione per il progetto App Builder. Attivato impostando l'annotazione require-adobe-auth su true in manifest.yml.

Accedere ad altre API Adobe access-adobe-apis

Aggiungere i servizi API all'area di lavoro della console Asset Compute creata durante la configurazione. Questi servizi fanno parte del token di accesso JWT generato da Asset Compute Service. Il token e le altre credenziali sono accessibili all'interno dell'oggetto azione dell'applicazione params.

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

Trasmettere le credenziali per i sistemi di terze parti pass-credentials-for-tp

Per gestire le credenziali per altri servizi esterni, trasmettile come parametri predefiniti sulle azioni. Vengono crittografati automaticamente in transito. Per ulteriori informazioni, vedere creazione di azioni nella Guida per gli sviluppatori di Adobe I/O Runtime. Quindi impostale utilizzando le variabili di ambiente durante la distribuzione. È possibile accedere a questi parametri nell'oggetto params all'interno dell'azione.

Impostare i parametri predefiniti all'interno di inputs in 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'espressione $VAR legge il valore da una variabile di ambiente denominata VAR.

Durante lo sviluppo, è possibile assegnare il valore nel file .env locale. Il motivo è che aio importa automaticamente le variabili di ambiente da .env file, insieme alle variabili impostate dalla shell di avvio. In questo esempio, il file .env ha l'aspetto seguente:

#...
SECRET_KEY=secret-value

Per la distribuzione di produzione è possibile impostare le variabili di ambiente nel sistema CI, ad esempio utilizzando i segreti nelle azioni GitHub. Infine, accedi ai parametri predefiniti all’interno dell’applicazione in quanto tale:

const key = params.secretKey;

Ridimensionamento delle applicazioni sizing-workers

Un'applicazione viene eseguita in un contenitore nell'Adobe I/O Runtime con limiti che può essere configurato tramite manifest.yml:

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

A causa dell’elaborazione intensiva eseguita dalle applicazioni Asset Compute, è necessario regolare questi limiti per ottenere prestazioni ottimali (abbastanza grandi da gestire le risorse binarie) ed efficienza (senza sprecare risorse a causa della memoria contenitore non utilizzata).

Il timeout predefinito per le azioni in fase di esecuzione è di un minuto, ma può essere aumentato impostando il limite di timeout (in millisecondi). Se prevedi di elaborare file di dimensioni maggiori, aumenta questo tempo. Considera il tempo totale necessario per scaricare l’origine, elaborare il file e caricare la rappresentazione. Se un’azione si interrompe per timeout, ovvero non restituisce l’attivazione prima del limite di timeout specificato, Runtime elimina il contenitore e non lo riutilizza.

Le applicazioni di Asset compute per natura tendono ad essere collegate alla rete e al disco. Il file di origine deve essere scaricato per primo. L’elaborazione richiede spesso molte risorse, quindi le rappresentazioni risultanti vengono caricate di nuovo.

È possibile specificare la memoria allocata a un contenitore di azioni in megabyte utilizzando il parametro memorySize. Attualmente, questo parametro definisce anche la quantità di accesso alla CPU che il contenitore ottiene e, soprattutto, è un elemento chiave del costo di utilizzo di Runtime (i contenitori più grandi costano di più). Utilizzare un valore maggiore quando l'elaborazione richiede una quantità maggiore di memoria o CPU, ma prestare attenzione a non sprecare risorse, poiché più grandi sono i contenitori, minore è la velocità effettiva complessiva.

Inoltre, è possibile controllare la concorrenza delle azioni all'interno di un contenitore utilizzando l'impostazione concurrency. Questa impostazione corrisponde al numero di attivazioni simultanee ottenute da un singolo contenitore (della stessa azione). In questo modello, il contenitore delle azioni è simile a un server Node.js che riceve più richieste simultanee, fino a tale limite. Il valore predefinito memorySize nel runtime è impostato su 200 MB, ideale per le azioni App Builder di dimensioni inferiori. Ad Asset compute, questo valore predefinito può essere eccessivo a causa della maggiore complessità dell'elaborazione locale e dell'utilizzo del disco. Alcune applicazioni, a seconda dell’implementazione, potrebbero non funzionare correttamente con le attività simultanee. L’SDK di Asset compute garantisce che le attivazioni siano separate scrivendo file in diverse cartelle univoche.

Verificare le applicazioni per trovare i numeri ottimali per concurrency e memorySize. Contenitori più grandi = un limite di memoria più alto potrebbe consentire una maggiore concorrenza, ma potrebbe anche sprecare per un traffico più basso.