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

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

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

Adobe aio-cli がローカルにインストールされていることを確認します。

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

資格情報の追加 add-credentials

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

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

開発者が Asset Compute service を使用してカスタムアプリを評価するためのツールでは、クラウドストレージコンテナを使用する必要があります。 このコンテナは、テストファイルの保存や、アプリで生成されたレンディションの受信と表示に不可欠です。

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

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

開発ツールの後続の資格情報を .env ファイルに挿入します。 ファイルは、App Builder プロジェクトのルートにあります。

アプリケーションの実行 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"
    }
]

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

アドビ提供のサンプルアプリケーションの試行 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.yml で require-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

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

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

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 パラメーターを使用して、アクションコンテナに割り当てられるメモリをメガバイト単位で指定できます。 現在、このパラメーターは、コンテナが取得する CPU アクセスの量も定義し、最も重要なのは、Runtime の使用コストの重要な要素であることです（コンテナが大きいほどコストが大きくなります）。 処理に多くのメモリや CPU が必要な場合は、ここで大きな値を使用しますが、コンテナが大きくなるほど全体的なスループットが低下するので、リソースを無駄にしないように注意してください。

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

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