AEM as a Cloud Serviceへのプログラマティックアセットのアップロード
aem-upload Node.js ライブラリを使用するクライアントアプリケーションを使用して、AEM as a Cloud Service環境にアセットをアップロードする方法について説明します。
学習内容
このチュートリアルでは、次の内容について説明します。
- 直接バイナリアップロード アプローチを使用して、aem-upload Node.js ライブラリを使用してAEM as a Cloud Service環境(RDE、Dev、Stage、Prod)にアセットをアップロードする方法。
- aem-asset-upload-sample アプリケーションを設定して実行し、AEM as a Cloud Service環境にアセットをアップロードする方法。
- サンプルアプリケーションコードを確認し、実装の詳細を理解します。
- AEM as a Cloud Service環境へのプログラマティック アセットのアップロードに関するベストプラクティスについて説明します。
直接バイナリアップロードのアプローチについて
ダイレクトバイナリアップロード アプローチにより、ソースシステム からAEM as a Cloud Service環境のクラウドストレージに 事前署名されたURL を使用してファイルを直接アップロードできます。 これにより、AEMのJava プロセスを介してバイナリデータをルーティングする必要がなくなり、アップロードの高速化とサーバー負荷の軽減が実現します。
サンプルアプリケーションを実行する前に、直接バイナリアップロードフローについて説明します。
直接バイナリアップロードフローでは、バイナリデータは事前署名済みのURLを使用してクラウドストレージに直接アップロードされます。 AEM as a Cloud Serviceは、事前署名済みURLの生成や、アップロードの完了に関するAEM Asset Compute サービスへの通知など、軽量な処理を担当します。 次の論理フロー図は、直接バイナリアップロードフローを示しています。
aem アップロードライブラリ
aem-upload Node.js ライブラリは、直接バイナリアップロード アプローチの実装の詳細を抽象化します。 アップロードプロセスを調整するために2つのクラスを提供します。
- FileSystemUpload - ローカルファイルシステムからファイルをアップロードする際に、ディレクトリ構造のサポートを含めて使用します
- DirectBinaryUpload - ストリームやバッファーからのアップロードなど、バイナリ アップロード プロセスをより細かく制御するために使用します
サンプルアプリケーション
プログラムによるアセットのアップロードプロセスを学習するには、aem-asset-upload-sample アプリケーションを使用します。 サンプルアプリケーションでは、aem-upload ライブラリのFileSystemUploadとDirectBinaryUploadの両方のクラスの使用について説明します。
前提条件
サンプルアプリケーションを実行する前に、次の前提条件を満たしていることを確認してください。
- Rapid Development Environment (RDE)やDev EnvironmentなどのAEM as a Cloud Service オーサー環境。
- Node.js (最新のLTS バージョン)
- Node.jsとnpmの基本的な理解
サンプルアプリケーションのダウンロード
-
aem-asset-upload-sample アプリケーションのzip ファイルをダウンロードして抽出します。
code language-bash $ unzip aem-asset-upload-sample.zip -
抽出したフォルダーをお気に入りのコードエディターで開きます。
code language-bash $ cd aem-asset-upload-sample $ code . -
コードエディターターミナルを使用して、依存関係をインストールします。
code language-bash $ npm install
サンプルアプリケーションの設定
サンプルアプリケーションを実行する前に、AEM オーサーのURL、認証方法、アセットフォルダーパスなど、必要なAEM as a Cloud Service環境の詳細で設定する必要があります。
aem-upload Node.js ライブラリでサポートされている認証方法は、複数あります。 次の表は、サポートされている 認証方法 とその目的をまとめたものです。
サンプルアプリケーションを設定するには、次の手順に従います。
-
env.exampleファイルを.envファイルにコピーします。code language-bash $ cp env.example .env -
.envファイルを開き、AEM_URL環境変数をAEM as a Cloud Service オーサーURLで更新します。 -
次のオプションから認証方法を選択し、対応する環境変数を更新します。
基本認証を使用するには、AEM as a Cloud Service環境でユーザーを作成する必要があります。
-
AEM as a Cloud Serviceにログインします。
-
ツール > セキュリティ > ユーザーに移動し、作成 ボタンをクリックします。
-
ユーザーの詳細を入力
-
「グループ」タブで、DAM ユーザー グループを追加します。 「保存して閉じる」ボタンをクリックします。
-
作成したユーザーのユーザー名とパスワードを使用して、
AEM_USERNAMEおよびAEM_PASSWORD環境変数を更新します。
ローカル開発トークンを取得するには、AEM Developer Consoleを使用する必要があります。 生成されるトークンは、JSON Web Token (JWT)タイプです。
-
Adobe Cloud Managerにログインし、目的の Environment の詳細ページに移動します。 「」をクリックします…」 Developer Consoleを選択します。
-
AEM Developer Consoleにログインし、新しいコンソール ボタンを使用して、新しいコンソールに切り替えます。
-
ツール セクションから、統合を選択し、ローカルトークンを取得 ボタンをクリックします。
-
トークン値をコピーし、トークン値で
AEM_BEARER_TOKEN環境変数を更新します。
ローカル開発トークンは24時間有効で、トークンを生成したユーザーに対して発行されます。
サービス資格情報を取得するには、AEM Developer Consoleを使用する必要があります。 これは、jwt-auth npm モジュールを使用してJSON Web Token (JWT) タイプのトークンを生成するために使用されます。
-
Adobe Cloud Managerにログインし、目的の Environment の詳細ページに移動します。 「」をクリックします…」 Developer Consoleを選択します。
-
AEM Developer Consoleにログインし、新しいコンソール ボタンを使用して、新しいコンソールに切り替えます。
-
「ツール」セクションから、統合を選択し、新しいテクニカルアカウントを作成 ボタンをクリックします。
-
「表示」オプションをクリックして、サービス資格情報JSONをコピーします。
-
サンプルアプリケーションのルートに
service-credentials.jsonファイルを作成し、サービス資格情報JSONをファイルに貼り付けます。 -
Service-credentials.json ファイルへのパスを使用して、
AEM_SERVICE_CREDENTIALS_FILE環境変数を更新します。 -
アセットをAEM as a Cloud Service環境にアップロードするために必要な権限がサービス資格情報ユーザーに付与されていることを確認します。 詳しくは、AEM ページでのアクセスの設定を参照してください。
次に、3つの認証方法をすべて設定した完全なサンプル .env ファイルを示します。
# AEM Environment Configuration
# Copy this file to .env and fill in your AEM as a Cloud Service details
# AEM as a Cloud Service Author URL (without trailing slash)
# Example: https://author-p12345-e67890.adobeaemcloud.com
AEM_URL=https://author-p63947-e1733365.adobeaemcloud.com
# Upload Configuration
# Target folder in AEM DAM where assets will be uploaded
TARGET_FOLDER=/content/dam
# DirectBinaryUpload Remote URLs (required for DirectBinaryUpload example)
# URLs for remote files to upload in the DirectBinaryUpload example
# These demonstrate uploading from remote sources (URLs, CDNs, APIs)
REMOTE_FILE_URL_1=https://placehold.co/600x400/red/white?text=Adobe+Experience+Manager+Assets
################################################################
# Authentication - Choose one of the following methods:
################################################################
# Method 1: Service Credentials (RECOMMENDED for production)
# Download service credentials JSON from AEM Developer Console and save it locally
# Then provide the path to the file here
AEM_SERVICE_CREDENTIALS_FILE=./service-credentials.json
# Method 2: Bearer Token Authentication (for manual testing)
AEM_BEARER_TOKEN=eyJhbGciOiJSUzI1NiIsIng1dSI6Imltc19uYTEta2V5LWF0LTEuY2VyIiwia2lkIjoiaW1zX25hM....fsdf-Rgt5hm_8FHutTyNQnkj1x1SUs5OkqUfJaGBaKBKdqQ
# Method 3: Basic Authentication (for development/testing only)
AEM_USERNAME=asset-uploader-local-user
AEM_PASSWORD=asset-uploader-local-user
# Optional: Enable detailed logging
DEBUG=false
サンプルアプリケーションの実行
サンプルアプリケーションでは、サンプルアセットをAEM as a Cloud Serviceにアップロードする3つの異なる方法を紹介しています。
- FileSystemUpload - ディレクトリ構造をサポートし、自動フォルダー作成を行うローカル ファイルシステムからファイルをアップロードします
- DirectBinaryUpload - リモートファイル をアップロードします。 ファイルバイナリは、AEM as a Cloud Service環境にアップロードする前にメモリにバッファリングされます。
- バッチアップロード – 自動再試行ロジックとエラー回復を使用して、ローカルファイルシステムから複数のファイルを一括でアップロードします。 バックグラウンドでは、
FileSystemUploadクラスを使用して、ローカルファイルシステムからファイルをアップロードします。
アップロードするアセットはsample-assets フォルダーにあり、img、video、doc個のサブフォルダーに、いくつかのサンプルアセットが含まれています。
- サンプルアプリケーションを実行するには、次のコマンドを使用します。
$ npm start
- 次の選択肢から目的のオプション numberを入力します。
╔════════════════════════════════════════════════════════════╗
║ AEM Asset Upload Sample Application ║
║ Demonstrating @adobe/aem-upload library ║
╚════════════════════════════════════════════════════════════╝
Choose an upload method:
1. FileSystemUpload - Upload files from local filesystem with auto-folder creation
2. DirectBinaryUpload - Upload from remote URLs/streams to AEM
3. Batch Upload - Upload multiple files in batches with retry logic
4. Exit
次のタブに、各アップロードメソッドのAEM as a Cloud Service環境でのサンプルアプリケーションの実行、出力、アップロードされたアセットを示します。
FileSystemUploadオプションのサンプル アプリケーション出力:
| code language-bash |
|---|
|
-
AEM as a Cloud Service環境で
FileSystemUploadオプションを使用してAssetsがアップロードされました:
DirectBinaryUploadオプションのサンプル アプリケーション出力:
| code language-bash |
|---|
|
- AEM as a Cloud Service環境で
DirectBinaryUploadオプションを使用してAssetsがアップロードされました:
Batch Uploadオプションのサンプル アプリケーション出力:
| code language-bash |
|---|
|
- AEM as a Cloud Service環境で
Batch Uploadオプションを使用してAssetsがアップロードされました:
サンプルアプリケーションコードの確認
サンプルアプリケーションの主なエントリポイントはindex.js ファイルです。 選択をユーザーに促し、選択した例を実行するpromptUser関数が含まれています。
/**
* Prompts user for choice and executes the selected example
*/
function promptUser() {
rl.question(chalk.bold('Enter your choice (1-4): '), async (answer) => {
console.log('');
try {
switch (answer.trim()) {
case '1':
console.log(chalk.bold.green('\n▶ Running FileSystemUpload Example...\n'));
await filesystemUpload.main();
break;
case '2':
console.log(chalk.bold.green('\n▶ Running DirectBinaryUpload Example...\n'));
await directBinaryUpload.main();
break;
case '3':
console.log(chalk.bold.green('\n▶ Running Batch Upload Example...\n'));
await batchUpload.main();
break;
case '4':
rl.close();
return;
default:
console.log(chalk.red('\n✗ Invalid choice. Please enter 1, 2, 3, or 4.\n'));
}
// After example completes, ask if user wants to continue
rl.question(chalk.bold('\nPress Enter to return to menu or Ctrl+C to exit...'), () => {
displayMenu();
promptUser();
});
} catch (error) {
console.error(chalk.red('\n✗ Error:'), error.message);
rl.question(chalk.bold('\nPress Enter to return to menu...'), () => {
displayMenu();
promptUser();
});
}
});
}
完全なコードについては、サンプルアプリケーションのindex.js ファイルを参照してください。
次のタブは、各アップロードメソッドの実装の詳細を示しています。
FileSystemUpload クラスは、ディレクトリ構造のサポートと自動フォルダー作成を使用して、ローカルファイルシステムからファイルをアップロードするために使用されます。
| code language-javascript |
|---|
|
完全なコードについては、サンプルアプリケーションのexamples/filesystem-upload.js ファイルを参照してください。
DirectBinaryUpload クラスは、リモート ファイルをAEM as a Cloud Service環境にアップロードするために使用されます。
| code language-javascript |
|---|
|
完全なコードについては、サンプルアプリケーションのexamples/direct-binary-upload.js ファイルを参照してください。
ファイルをバッチに分割し、自動再試行ロジックとエラー回復を使用してファイルをバッチにアップロードします。 バックグラウンドでは、FileSystemUpload クラスを使用して、ローカルファイルシステムからファイルをアップロードします。
| code language-javascript |
|---|
|
完全なコードについては、サンプルアプリケーションのexamples/batch-upload.js ファイルを参照してください。
また、サンプルアプリケーションのREADME.md ファイルには、サンプルアプリケーションの詳細ドキュメントが含まれています。
ベストプラクティス
-
適切な認証方法を選択:
本番環境のサービス資格情報、ローカル開発トークン、およびBasic認証は、開発/テストにのみ使用します。 アセットをAEM as a Cloud Service環境にアップロードするために必要な権限がサービス資格情報ユーザーに付与されていることを確認します。 -
適切なアップロード方法を選択:
自動フォルダー作成機能を備えたローカルファイルにはFileSystemUpload、きめ細かい制御を備えたストリーム/バッファー/リモート URLにはDirectBinaryUpload、再試行ロジックを必要とする1000以上のファイルを備えた実稼動環境用のバッチアップロードパターンを使用できます。 -
構造DirectBinaryUpload ファイル オブジェクトを正しく作成
必須フィールド { fileName, fileSize, blob: buffer, targetFolder }でblob プロパティ(バッファではない)を使用し、DirectBinaryUploadはフォルダーを自動作成しないことを覚えておいてください。 -
参照としてのサンプル アプリケーション:
サンプルアプリケーションは、プログラマティックアセットアップロードプロセスの実装の詳細に関する優れたリファレンスです。 実装の出発点として使用できます。