AEM as a Cloud Serviceへのプログラムによるアセットのアップロード
aem-upload Node.js ライブラリを使用するクライアントアプリケーションを使用して、AEM as a Cloud Service環境にアセットをアップロードする方法について説明します。
学習内容
このチュートリアルでは、次の内容について説明します。
- 直接バイナリアップロード アプローチを使用して、aem-upload Node.js ライブラリを使用してアセットをAEM as a Cloud Service環境(RDE、開発、ステージ、実稼動)にアップロードする方法。
- aem-asset-upload-sample アプリケーションを設定および実行して、AEM as a Cloud Service環境にアセットをアップロードする方法。
- サンプルアプリケーションコードを確認し、実装の詳細を理解します。
- AEM as a Cloud Service環境へのプログラムによるアセットのアップロードに関するベストプラクティスを理解します。
直接バイナリアップロード アプローチについて
直接バイナリアップロード アプローチを使用すると、事前署名済み URL を使用して、AEM as a Cloud Service環境のソースシステムから クラウドストレージに直接 ファイルをアップロードできます。 AEMの Java プロセスを使用してバイナリデータをルーティングする必要がなくなり、アップロードの高速化とサーバー負荷の軽減を実現します。
サンプルアプリケーションを実行する前に、直接バイナリアップロードのフローを理解しましょう。
直接バイナリアップロードフローでは、事前署名済み URL を使用してバイナリデータがクラウドストレージに直接アップロードされます。 AEM as a Cloud Serviceは、事前署名済み URL の生成や、アップロード完了に関するAEM Asset Compute サービスへの通知など、軽量の処理を行います。 次の論理フロー図は、直接バイナリアップロードフローを示しています。
aem-upload ライブラリ
aem-upload Node.js ライブラリは、直接バイナリアップロード アプローチの実装の詳細を抽象化します。 アップロードプロセスを調整するために、次の 2 つのクラスが用意されています。
- FileSystemUpload - ディレクトリ構造のサポートなど、ローカルファイルシステムからのファイルのアップロード時に使用します
- DirectBinaryUpload - ストリームまたはバッファーからのアップロードなど、バイナリアップロードプロセスのより詳細な制御に使用します
サンプルアプリケーション
aem-asset-upload-sample アプリケーションを使用して、プログラムによるアセットのアップロードプロセスを学びます。 サンプルアプリケーションは、FileSystemUploadaem-uploadDirectBinaryUpload ライブラリから クラスと クラスの両方を使用する方法を示しています。
前提条件
サンプルアプリケーションを実行する前に、次の前提条件を満たしていることを確認してください。
- 迅速な開発環境(RDE)、開発環境などの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 as a Cloud Service オーサー URL でAEM_URL環境変数を更新します。 -
以下のオプションから認証方法を選択し、対応する環境変数を更新します。
基本認証を使用するには、AEM as a Cloud Serviceでユーザーを作成する必要があります。
-
AEM as a Cloud Service環境にログインします。
-
ツール/セキュリティ/ユーザー に移動し、「作成」ボタンをクリックします。
-
ユーザーの詳細を入力します
-
「グループ」タブで DAM ユーザー グループを追加します。 「保存して閉じる ボタンをクリックします。
-
AEM_USERNAMEおよびAEM_PASSWORDの環境変数を、作成したユーザーのユーザー名とパスワードで更新します。
ローカル開発トークンを取得するには、AEM Developer Consoleを使用する必要があります。 生成されたトークンのタイプは JSON Web トークン(JWT)です。
-
Adobe Cloud Managerにログインし 目的の 環境 詳細ページに移動します。 「」。…「 をクリックし、「Developer Console」を選択します。
-
AEM Developer Consoleにログインし、「新しいコンソール ボタンを使用して新しいコンソールに切り替えます。
-
「ツール」セクションで「統合」を選択し、「ローカルトークンを取得」ボタンをクリックします。
-
トークン値をコピーし、そのトークン値を使用して
AEM_BEARER_TOKEN環境変数を更新します。
ローカル開発トークンは 24 時間有効で、トークンを生成したユーザーに対して発行されます。
サービス資格情報を取得するには、AEM Developer Consoleを使用する必要があります。 jwt-auth npm モジュールを使用して、JSON web トークン(JWT)タイプのトークンを生成するために使用されます。
-
Adobe Cloud Managerにログインし 目的の 環境 詳細ページに移動します。 「」。…「 をクリックし、「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
- 次の選択肢から目的のオプション 数値 を入力します。
╔════════════════════════════════════════════════════════════╗
║ 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 ファイルには、サンプルアプリケーションの詳細なドキュメントが含まれています。
ベストプラクティス
-
適切な認証方法の選択:
実稼動環境のサービス資格情報、開発/テスト専用のローカル開発トークンおよび基本認証を使用します。 サービス資格情報のユーザーが、AEM as a Cloud Service環境にアセットをアップロードするために必要な権限を持っていることを確認します。 -
適切なアップロード方法を選択:
自動フォルダー作成を使用するローカルファイルには FileSystemUpload を、きめ細かな制御を使用するストリーム/バッファー/リモート URL には DirectBinaryUpload を、再試行ロジックが必要な 1000 以上のファイルを含む実稼動環境にはバッチアップロードパターンを使用します。 -
DirectBinaryUpload ファイル オブジェクトを正しく構造化する
必須フィールド { fileName, fileSize, blob: buffer, targetFolder } を使用して blob プロパティ(バッファーではない)を使用します。DirectBinaryUpload では、フォルダーは自動作成されないことに注意してください。 -
参照としてのサンプルアプリケーション:
サンプルアプリケーションは、プログラムによるアセットのアップロードプロセスの実装の詳細を示す参考資料です。 独自の実装の出発点として使用できます。