カスタムアプリケーションの開発 develop

カスタムアプリケーションの開発を始める前に、以下をおこないます。

カスタムアプリケーションの作成 create-custom-application

Adobe I/O CLI がローカルにインストールされていることを確認します。

  1. カスタムアプリケーションを作成するには、App Builder プロジェクトを作成します。それには、ターミナルで aio app init <app-name> を実行します。

    まだログインしていない場合は、このコマンドを実行すると、Adobe ID で Adobe Developer Console にログインするように促すメッセージがブラウザーに表示されます。CLI からのログインについて詳しくは、こちらを参照してください。

    ログインすることをお勧めします。問題が発生した場合は、指示に従って、ログインせずにアプリを作成します。

  2. ログイン後、CLI のプロンプトに従って、アプリケーションに使用する OrganizationProjectWorkspace を選択します。環境の設定で作成したプロジェクトとワークスペースを選択します。「Which extension point(s) do you wish to implement ?」というプロンプトが表示されたら、必ず 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. Which Adobe I/O App features do you want to enable for this project?」というプロンプトが表示されたら、「Actions」を選択します。Web アセットは別の認証および承認チェックを使用するので、必ず「Web Assets」オプションの選択を解除してください。

    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. Which type of sample actions do you want to create?」というプロンプトが表示されたら、必ず 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. 残りのプロンプトに従い、Visual Studio Code(または、お好きなコードエディター)で新しいアプリケーションを開きます。カスタムアプリケーションの基礎モードとサンプルコードが含まれています。

    App Builder アプリの主なコンポーネントについては、こちらを参照してください。

    テンプレートアプリケーションでは、アプリケーションレンディションのアップロード、ダウンロード、オーケストレーションにアドビの Asset Compute SDK を利用するので、開発者はカスタムアプリケーションロジックを実装するだけで済みます。actions/<worker-name> フォルダー内の index.js ファイルがカスタムアプリケーションコードの追加先です。

カスタムアプリの例とアイデアについては、カスタムアプリケーションの例を参照してください。

資格情報の追加 add-credentials

アプリケーションの作成時にログインすると、App Builder 資格情報のほとんどが ENV ファイルに収集されます。ただし、開発者ツールを使用するには、追加の資格情報が必要です。

開発者ツールストレージの資格情報 developer-tool-credentials

カスタムアプリケーションを実際の Asset Compute service でテストするために使用する開発者ツールには、テストファイルをホストしたり、アプリケーションで生成されたレンディションを受け取って表示したりするためのクラウドストレージコンテナが必要です。

NOTE
これは、Adobe Experience Manager as a Cloud Service のクラウドストレージとは別のものです。これは、Asset Compute の開発者ツールを使用した開発およびテストにのみ当てはまります。

サポート対象のクラウドストレージコンテナにアクセスできることを確認してください。このコンテナは、異なるプロジェクトの複数の開発者が必要に応じて共有できます。

ENV ファイルへの資格情報の追加 add-credentials-env-file

App Builder プロジェクトのルートにある ENV ファイルに、開発者ツール用の次の資格情報を追加します。

  1. App Builder プロジェクトにサービスを追加する際に作成された、秘密鍵ファイルへの絶対パスを追加します。

    code language-conf
    ASSET_COMPUTE_PRIVATE_KEY_FILE_PATH=
    
  2. Adobe Developer Console からファイルをダウンロードします。プロジェクトのルートに移動し、右上隅の「すべてをダウンロード」をクリックします。ファイルは「<namespace>-<workspace>.json」というファイル名でダウンロードされます。次のいずれかの操作をおこないます。

    • ファイル名を「console.json」に変更し、プロジェクトのルートに移動します。

    • オプションとして、Adobe Developer Console 統合 JSON ファイルへの絶対パスを追加できます。これは、プロジェクトワークスペースにダウンロードされる console.json ファイルと同じです。

      code language-conf
      ASSET_COMPUTE_INTEGRATION_FILE_PATH=
      
  3. S3 ストレージか Azure ストレージのいずれかの資格情報を追加します。1 つのクラウドストレージソリューションへのアクセスのみ必要です。

    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
config.json ファイルには資格情報が含まれています。共有を防ぐため、プロジェクト内で、.gitignore ファイルに JSON ファイルを追加します。.env ファイルと .aio ファイルにも同じ操作を実行します。

アプリケーションの実行 run-custom-application

Asset Compute 開発者ツールを使用してアプリケーションを実行する前に、資格情報を適切に設定します。

開発者ツールでアプリケーションを実行するには、aio app run コマンドを使用します。これにより、ローカルマシン上に Adobe I/O Runtime へのアクションがデプロイされ、ローカルマシンで開発ツールが起動します。このツールは、開発中にアプリケーションリクエストのテストに使用されます。レンディションリクエストの例を次に示します。

"renditions": [
    {
        "worker": "https://1234_my_namespace.adobeioruntime.net/api/v1/web/example-custom-worker-master/worker",
        "name": "image.jpg"
    }
]
NOTE
run コマンドで --local フラグを使用しないでください。このフラグは、Asset Compute カスタムアプリケーションと Asset Compute 開発者ツールでは機能しません。カスタムアプリケーションは Asset Compute Service によって呼び出され、開発者のローカルマシンで実行中のアクションにはアクセスできません。

アプリケーションのテストとデバッグの方法については、こちらを参照してください。カスタムアプリケーションの開発が完了したら、カスタムアプリケーションをデプロイします。

アドビ提供のサンプルアプリケーションの試行 try-sample

次のサンプルカスタムアプリケーションが用意されています。

テンプレートカスタムアプリケーション template-custom-application

worker-basic はテンプレートアプリケーションです。ソースファイルをコピーするだけで、レンディションが生成されます。このアプリのコンテンツは、aio アプリケーションの作成で Adobe Asset Compute を選択した場合に受け取るテンプレートになります。

アプリケーションファイル worker-basic.js では、asset-compute-sdk を使用してソースファイルをダウンロードし、各レンディション処理をオーケストレーションして、結果のレンディションをクラウドストレージにアップロードします。

アプリケーションコード内で定義されている renditionCallback が、すべてのアプリケーション処理ロジックが実行される場所になります。worker-basic のレンディションコールバックは、ソースファイルの内容をレンディションファイルにコピーするだけです。

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

外部 API の呼び出し call-external-api

アプリケーションコードで外部 API を呼び出して、アプリケーションの処理に役立てることができます。外部 API を呼び出すアプリケーションファイルの例を以下に示します。

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

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

例えば、worker-animal-pictures では、node-httptransfer ライブラリを使用してウィキメディアの静的 URL に対して取得リクエストを実行しています。

カスタムパラメーターの受け渡し pass-custom-parameters

カスタム定義のパラメーターをレンディションオブジェクトに渡すことができます。これらは、アプリケーション内の rendition 手順で参照できます。レンディションオブジェクトの例を次に示します。

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

カスタムパラメーターにアクセスするアプリケーションファイルの例を次に示します。

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 では、カスタムパラメーター animal を渡して、どのファイルをウィキメディアから取得するかを指定しています。

認証と承認のサポート authentication-authorization-support

Asset Compute カスタムアプリケーションでは、デフォルトで App Builder アプリケーションの承認および認証チェックが行われます。これは、manifest.ymlrequire-adobe-auth 注釈を true に設定すると有効になります。

他の Adobe API へのアクセス access-adobe-apis

設定時に作成した Asset Compute コンソールワークスペースに API サービスを追加します。これらのサービスは、Asset Compute Service で生成された JWT アクセストークンの一部です。トークンとその他の資格情報には、アプリケーションアクションの 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

サードパーティ製システムの資格情報の受け渡し pass-credentials-for-tp

他の外部サービスの資格情報を扱うには、それらをアクションのデフォルトパラメーターとして渡します。これらは送信中に自動的に暗号化されます。詳しくは、Runtime 開発者ガイドでアクションの作成に関する説明を参照してください。次に、デプロイ時に環境変数を使用してそれらを設定します。これらのパラメーターには、アクション内の params オブジェクトでアクセスできます。

manifest.ymlinputs 内にデフォルトパラメーターを設定します。

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

$VAR 式は、VAR という名前の環境変数から値を読み取っています。

開発時に、この値をローカルの ENV ファイルに設定できます。aio では、呼び出し側のシェルで設定された変数に加えて、ENV ファイルから環境変数を自動的に読み取るからです。この例では、ENV ファイルは次のようになります。

#...
SECRET_KEY=secret-value

実稼働デプロイメントの場合は、GitHub アクションでのシークレットの使用など、CI システムで環境変数を設定する場合もあります。最後に、アプリケーション内で次のようにデフォルトパラメーターにアクセスします。

const key = params.secretKey;

アプリケーションのサイズ調整 sizing-workers

アプリケーションは、Adobe I/O Runtime のコンテナで実行されますが、その際に、manifest.yml で設定できる制限(下記参照)が適用されます。

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

Asset Compute アプリケーションで通常実行される処理が大規模になれば、最適なパフォーマンス(バイナリアセットを処理するのに十分な大きさを確保)と効率(未使用のコンテナメモリに起因するリソースの浪費を回避)を得るために、これらの制限を調整する必要性が高くなります。

Runtime ではアクションのデフォルトのタイムアウトは 1 分ですが、timeout の制限値(ミリ秒)を設定して増やすことができます。サイズの大きいファイルを処理することが想定される場合は、この時間を長くしてください。ソースのダウンロード、ファイルの処理、レンディションのアップロードにかかる合計時間を考慮します。アクションがタイムアウトした場合、つまり、指定されたタイムアウト上限までにアクティベーションが返されない場合、Runtime はコンテナを破棄し、再利用しません。

Asset Compute アプリケーションは本来、ネットワークとディスクの入力および出力が制限される傾向があります。ソースファイルをまずダウンロードする必要があり、処理はリソースに負荷がかかることが多く、結果として生成されるレンディションが再びアップロードされます。

アクションコンテナが使用できるメモリは、memorySize に MB 単位で指定します。現在のところ、この値はコンテナが取得する CPU アクセスの量も定義していますが、最も重要なのは、この値が Runtime の使用コストの主要な要素になっていることです(コンテナが大きいほどコストが大きくなります)。処理に必要なメモリや CPU の量が多い場合は、ここでより大きい値を指定しますが、コンテナが大きいほど全体的なスループットが低下するので、リソースを無駄にしないように注意してください。

さらに、この concurrency 設定を使用して、コンテナ内でのアクションの同時実行性を制御することができます。これは、1 つのコンテナが(同じアクションについて)同時に受け取るアクティベーションの数です。このモデルでは、アクションコンテナは、複数の同時リクエストをその上限まで受け取る Node.js サーバーのようなものです。これを設定しないと、Runtime のデフォルトは 200 になります。これは、小規模な App Builder アクションには適していますが、Asset Compute アプリケーションではローカル処理とディスクアクティビティの負荷が高くなることを考えると、Asset Compute アプリケーションには通常大きすぎます。実装によっては、一部のアプリケーションは、同時実行アクティビティではうまく動作しない場合もあります。Asset Compute SDK を使用すると、一意の異なるフォルダーにファイルを書き込むことで、アクティベーションが確実に分離されます。

アプリケーションをテストして、concurrencymemorySize の最適な値を見つけてください。コンテナが大きい、つまりメモリ上限が大きいと、同時実行性が高くなる可能性がありますが、同時に、トラフィック量が少ない場合にリソースが無駄になる可能性があります。

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