Desenvolver um aplicativo personalizado

Antes de começar a desenvolver um aplicativo personalizado:

Criar um aplicativo personalizado

Certifique-se de ter a Adobe I/O CLI instalada localmente.

  1. Para criar um aplicativo personalizado, crie um aplicativo Firefly. Para fazer isso, execute aio app init <app-name> no terminal.

    Se você ainda não tiver feito logon, este comando solicitará que você faça logon no Adobe Developer Console com sua Adobe ID. Consulte aqui para obter mais informações sobre como fazer logon pela cli.

    O Adobe recomenda fazer logon. Se tiver problemas, siga as instruções para criar um aplicativo sem fazer logon.

  2. Depois de fazer logon, siga os prompts na CLI e selecione os Organization, Project e Workspace para usar no aplicativo. Escolha o projeto e o espaço de trabalho criados ao configurar seu ambiente.

    $ aio app init <app-name>
    Retrieving information from Adobe I/O Console.
    ? Select Org My Adobe Org
    ? Select Project MyFireflyProject
    ? Select Workspace myworkspace
    create console.json
    
  3. Quando solicitado com Which Adobe I/O App features do you want to enable for this project?, selecione Actions. Certifique-se de desmarcar a opção Web Assets, pois os ativos da Web usam diferentes verificações de autenticação e autorização.

    ? 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. Quando solicitado Which type of sample actions do you want to create?, selecione 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 o resto dos prompts e abra o novo aplicativo no Visual Studio Code (ou seu editor de código favorito). Ele contém o scaffolding e o código de amostra de um aplicativo personalizado.

    Leia aqui sobre os componentes principais de um aplicativo Firefly.

    O aplicativo modelo aproveita nosso Asset compute SDK para fazer upload, baixar e orquestrar as execuções do aplicativo, de modo que os desenvolvedores precisam apenas implementar a lógica do aplicativo personalizado. Na pasta actions/<worker-name>, o arquivo index.js é onde o código de aplicativo personalizado deve ser adicionado.

Consulte exemplo de aplicativos personalizados para obter exemplos e ideias para aplicativos personalizados.

Adicionar credenciais

À medida que você faz logon ao criar o aplicativo, a maioria das credenciais do Firefly é coletada em seu arquivo ENV. No entanto, usar a ferramenta de desenvolvedor requer credenciais adicionais.

Credenciais de armazenamento da ferramenta de desenvolvedor

A ferramenta de desenvolvedor usada para testar aplicativos personalizados com o Asset Compute service real requer um contêiner de armazenamento em nuvem para hospedar arquivos de teste e para receber e exibir representações geradas por aplicativos.

OBSERVAÇÃO

Isso é separado do armazenamento em nuvem de Adobe Experience Manager como um Cloud Service. Ela só se aplica ao desenvolvimento e teste com a ferramenta de desenvolvedor do Asset compute.

Certifique-se de ter acesso a um contêiner de armazenamento em nuvem compatível. Esse contêiner pode ser compartilhado por vários desenvolvedores em diferentes projetos, conforme necessário.

Adicionar credenciais ao arquivo ENV

Adicione as seguintes credenciais para a ferramenta de desenvolvedor ao arquivo ENV na raiz do projeto Firefly:

  1. Adicione o caminho absoluto ao arquivo de chave privada criado ao adicionar serviços ao Projeto Firefly:

    ASSET_COMPUTE_PRIVATE_KEY_FILE_PATH=
    
  2. Baixe o arquivo do Console do desenvolvedor do Adobe. Vá para a raiz do projeto e clique em "Baixar tudo" no canto superior direito. O arquivo é baixado com <namespace>-<workspace>.json como o nome do arquivo. Faça uma das seguintes opções:

    • Renomeie o arquivo como console.json e mova-o para a raiz do seu projeto.

    • Como opção, você pode adicionar o caminho absoluto ao arquivo JSON de integração do Console do Desenvolvedor. Este é o mesmo arquivo console.json que é baixado no espaço de trabalho do projeto.

      ASSET_COMPUTE_INTEGRATION_FILE_PATH=
      
  3. Adicione as credenciais de armazenamento do S3 ou do Azure. Você só precisa acessar uma solução de armazenamento em nuvem.

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

O arquivo config.json contém credenciais. De dentro do seu projeto, adicione o arquivo JSON ao arquivo .gitignore para evitar o compartilhamento. O mesmo se aplica aos arquivos .env e .aio.

Execute o aplicativo

Antes de executar o aplicativo com a Ferramenta de Desenvolvedor do Asset compute, configure corretamente as credenciais.

Para executar o aplicativo na ferramenta do desenvolvedor, use o comando aio app run. Ele implanta a ação para Adobe I/O Tempo de execução e inicia a ferramenta de desenvolvimento no computador local. Essa ferramenta é usada para testar solicitações de aplicativos durante o desenvolvimento. Veja um exemplo de solicitação de representação:

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

Não use o sinalizador --local com o comando run. Ele não funciona com aplicativos personalizados Asset Compute e a ferramenta Asset compute Developer. Os aplicativos personalizados são chamados pelo Asset Compute Service que não pode acessar ações em execução nos computadores locais do desenvolvedor.

Consulte aqui como testar e depurar seu aplicativo. Quando terminar de desenvolver seu aplicativo personalizado, implante seu aplicativo personalizado.

Experimente o aplicativo de amostra fornecido pelo Adobe

Veja a seguir exemplos de aplicativos personalizados:

Aplicativo personalizado de modelo

O worker-basic é um aplicativo de modelo. Ele gera uma representação simplesmente copiando o arquivo de origem. O conteúdo deste aplicativo é o template recebido ao escolher Adobe Asset Compute na criação do aplicativo aio.

O arquivo do aplicativo, worker-basic.js usa o asset-compute-sdk para baixar o arquivo de origem, orquestrar cada processamento de representação e fazer upload das representações resultantes de volta para o armazenamento na nuvem.

O renditionCallback definido dentro do código do aplicativo, é onde executar toda a lógica de processamento do aplicativo. O retorno de chamada de representação em worker-basic simplesmente copia o conteúdo do arquivo de origem para o arquivo de representação.

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

Chamar uma API externa

No código do aplicativo, você pode fazer chamadas de API externas para ajudar no processamento do aplicativo. Um exemplo de arquivo de aplicativo que chama a API externa está abaixo.

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

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

Por exemplo, o worker-animal-pictures faz uma solicitação de busca para um URL estático da Wikimedia usando a biblioteca node-httptransfer.

Envio de parâmetros personalizados

Você pode passar parâmetros definidos personalizados por meio dos objetos de representação. Eles podem ser referenciados dentro do aplicativo em rendition instruções. Um exemplo de objeto de representação é:

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

Um exemplo de um arquivo de aplicativo que acessa um parâmetro personalizado é:

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

O example-worker-animal-pictures transmite um parâmetro personalizado animal para determinar qual arquivo buscar na Wikimedia.

Suporte à autenticação e autorização

Por padrão, os aplicativos personalizados do Asset compute vêm com as verificações de Autorização e Autenticação para aplicativos Firefly. Isso é ativado ao definir a anotação require-adobe-auth para true no manifest.yml.

Acesse outras APIs do Adobe

Adicione os serviços da API ao espaço de trabalho do Console Asset Compute criado na configuração. Esses serviços fazem parte do token de acesso JWT gerado por Asset Compute Service. O token e outras credenciais são acessíveis dentro do objeto de ação params do aplicativo.

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

Enviar credenciais para sistemas de terceiros

Para manipular credenciais para outros serviços externos, passe-as como parâmetros padrão nas ações. Eles são automaticamente criptografados em trânsito. Para obter mais informações, consulte criar ações no Guia do desenvolvedor do Runtime. Em seguida, defina-os usando variáveis de ambiente durante a implantação. Esses parâmetros podem ser acessados no objeto params dentro da ação .

Defina os parâmetros padrão dentro de inputs no manifest.yml:

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

A expressão $VAR lê o valor de uma variável de ambiente chamada VAR.

Durante o desenvolvimento, o valor pode ser definido no arquivo ENV local, pois aio lê automaticamente as variáveis de ambiente dos arquivos ENV, além das variáveis definidas no shell de chamada. Neste exemplo, o arquivo ENV tem a seguinte aparência:

#...
SECRET_KEY=secret-value

Para implantação de produção, é possível definir as variáveis de ambiente no sistema CI, por exemplo, usando segredos em Ações do GitHub. Por fim, acesse os parâmetros padrão dentro do aplicativo como tal:

const key = params.secretKey;

Dimensionamento de aplicativos

Um aplicativo é executado em um container em Adobe I/O Runtime com limits que pode ser configurado por meio do manifest.yml:

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

Devido ao processamento mais extenso normalmente feito por aplicativos Asset compute, é mais provável que seja necessário ajustar esses limites para desempenho ideal (grande o suficiente para lidar com ativos binários) e eficiência (não desperdiçar recursos devido à memória de contêiner não usada).

O tempo limite padrão para ações em Tempo de execução é de um minuto, mas pode ser aumentado ao configurar o limite timeout (em milissegundos). Se você espera processar arquivos maiores, aumente esse tempo. Considere o tempo total necessário para baixar a fonte, processar o arquivo e fazer upload da representação. Se uma ação expirar, ou seja, não retornar a ativação antes do tempo limite especificado, o Tempo de execução descarta o contêiner e não o reutilizará.

Por natureza, os aplicativos Asset compute tendem a ser de entrada ou saída de rede e disco. O arquivo de origem deve ser baixado primeiro, o processamento geralmente exige muitos recursos e, em seguida, as renderizações resultantes são carregadas novamente.

A memória disponível para um contêiner de ação é especificada por memorySize em MB. Atualmente, isso também define quanto acesso à CPU o contêiner recebe e, o mais importante, é um elemento essencial do custo de usar o Runtime (contêineres maiores custam mais). Use um valor maior aqui quando o processamento exigir mais memória ou CPU, mas tenha cuidado para não desperdiçar recursos, pois quanto maior for o contêiner, menor será a taxa de transferência geral.

Além disso, é possível controlar a simultaneidade de ação em um contêiner usando a configuração concurrency . Esse é o número de ativações simultâneas que um único contêiner (da mesma ação) recebe. Neste modelo, o contêiner de ação é como um servidor Node.js que recebe várias solicitações simultâneas, até esse limite. Se não estiver definido, o padrão em Tempo de Execução é 200, o que é ótimo para ações menores do Firefly, mas geralmente é muito grande para aplicativos Asset compute, dado seu processamento local mais intenso e atividade de disco. Alguns aplicativos, dependendo de sua implementação, também podem não funcionar bem com atividades simultâneas. O SDK do Asset compute garante que as ativações sejam separadas, gravando arquivos em pastas exclusivas diferentes.

Teste os aplicativos para encontrar os números ideais para concurrency e memorySize. Contêineres maiores = limite de memória mais alto pode permitir mais simultaneidade, mas também pode ser um desperdício para tráfego menor.

Nesta página