Adobe Experience Manager Assets デベロッパー向けの使用例、API、参考資料

このドキュメントは、Assets as a Cloud Service の開発者向けレコメンデーション、リファレンス資料およびリソースが含まれています。新しいアップロードモジュール、API リファレンス、後処理ワークフローで提供されるサポートに関する情報が含まれています。

Experience Manager Assets API と操作

Assets as a Cloud Service には、デジタルアセットをプログラミングで操作するためのいくつかの API が用意されています。各 API は、以下の表に示すように、特定の使用例をサポートしています。Assets ユーザーインターフェイス、Experience Manager デスクトップアプリ、Adobe Asset Link は、すべての操作または一部の操作をサポートしています。

アセットのアップロード

Experience Manager as a Cloud Service では、HTTP API を使用して、アセットをクラウドストレージに直接アップロードできます。バイナリファイルをアップロードする手順は次のとおりです。これらの手順は、Experience Manager JVM 内ではなく、外部アプリケーションで実行します。

1. HTTP リクエストを送信します。その結果、新しいバイナリをアップロードする意図が Experience Manager デプロイメントに通知されます。
2. 開始リクエストで提供される 1 つ以上の URI にバイナリのコンテンツを PUT 送信します。
3. HTTP リクエストを送信して、バイナリのコンテンツが正常にアップロードされたことをサーバーに通知します。

このアプローチで、アセットのアップロードをスケーラブルかつより効率的に処理できます。Experience Manager 6.5 と比較した場合の違いは次のとおりです。

• バイナリは Experience Manager を経由しません。AEM は、デプロイメント用に設定されたバイナリクラウドストレージを使用するアップロードプロセスを調整するだけです。
• バイナリクラウドストレージは、コンテンツ配信ネットワーク（CDN）または Edge ネットワークと連携します。CDN は、クライアントに近いアップロードエンドポイントを選択します。特に地理的に分散したチームでは、データが近くのエンドポイントに転送される距離が短いほど、アップロードのパフォーマンスとユーザーエクスペリエンスが向上します。

アップロードの開始

HTTP POST リクエストを目的のフォルダーに送信します。このフォルダーでアセットが作成または更新されます。このリクエストがバイナリファイルのアップロードを開始するものであることを示すセレクター .initiateUpload.json を含めます。例えば、アセットが作成されるフォルダーのパスが /assets/folder の場合、POST リクエストは POST https://[aem_server]:[port]/content/dam/assets/folder.initiateUpload.json のようになります。

リクエスト本文のコンテンツタイプは、次のフィールドを含んだ application/x-www-form-urlencoded 形式のデータにする必要があります。

• (string) fileName：必須。Adobe Experience Manager に表示されるアセットの名前
• (number) fileSize：必須。アップロードされるアセットのファイルサイズ（バイト単位）

各バイナリに必須フィールドが含まれている限り、単一のリクエストを使用して複数のバイナリのアップロードを開始できます。成功した場合は、リクエストへの応答として、201 ステータスコードと、次の形式の JSON データを含んだ本文が返されます。

{
    "completeURI": "(string)",
    "folderPath": "(string)",
    "files": [
        {
            "fileName": "(string)",
            "mimeType": "(string)",
            "uploadToken": "(string)",
            "uploadURIs": [
                "(string)"
            ],
            "minPartSize": (number),
            "maxPartSize": (number)
        }
    ]
}

• completeURI（文字列）：バイナリのアップロードが完了したら、この URI を呼び出します。URI は絶対 URI でも相対 URI でも構いません。クライアントはどちらでも処理できるはずです。つまり、値は "https://[aem_server]:[port]/content/dam.completeUpload.json" または "/content/dam.completeUpload.json" でも構いません。アップロードの完了を参照してください。
• folderPath（文字列）：バイナリがアップロードされるフォルダーの完全なパス。
• (files)（配列）：開始リクエストで提供されるバイナリ情報のリストの長さと順序に一致する要素のリスト。
• fileName（文字列）：対応するバイナリの名前（開始リクエストで指定されたもの）。この値は、完了リクエストに含まれます。
• mimeType（文字列）：対応するバイナリの MIME タイプ（開始リクエストで指定されたもの）。この値は、完了リクエストに含まれます。
• uploadToken（文字列）：対応するバイナリのアップロードトークン。この値は、完了リクエストに含まれます。
• uploadURIs（配列）：バイナリコンテンツのアップロード先となる完全な URI を表す文字列のリストです（バイナリのアップロードを参照）。
• minPartSize（数字）：複数の URI がある場合にいずれかの uploadURIs に提供されるデータの最小長（バイト単位）。
• maxPartSize（数字）：複数の URI がある場合にいずれかの uploadURIs に提供されるデータの最大長（バイト単位）。

バイナリのアップロード

アップロードを開始した場合の出力には、1 つ以上のアップロード URI 値が含まれています。複数の URI を指定した場合、クライアント側でバイナリを複数のパーツに分割し、各パーツの PUT リクエストを、提供されたアップロード URI に順に送信する場合があります。バイナリを複数に分割する場合は、次のガイドラインに従ってください。

• 分割したパーツのサイズは、最後のものを除き、minPartSize.以上でなければなりません。
• 各パーツのサイズは maxPartSize.以下でなければなりません。
• バイナリのサイズが maxPartSize を超えた場合は、バイナリを複数のパーツに分割してアップロードします。
• すべての URI を使用する必要はありません。

バイナリのサイズが maxPartSize 以下の場合は、バイナリ全体を単一のアップロード URI にアップロードすることもできます。複数のアップロード URI が指定された場合、最初のアップロード URI を使用し、残りは無視します。すべての URI を使用する必要はありません。

CDN エッジノードを使用すると、要求されたバイナリアップロードを高速化できます。

これを行う最も簡単な方法は、パーツサイズとして maxPartSize を使用することです。API 契約は、この値をパーツサイズとして使用する場合、バイナリをアップロードするのに十分なアップロード URI があることを保証します。これを行うには、各パーツに対して 1 つの URI を順に使用して、バイナリを maxPartSize サイズのパーツに分割します。最後の部分は、maxPartSize 以下の任意のサイズにできます。例えば、バイナリの合計サイズが 20,000 バイトで、minPartSize は 5,000 バイト、maxPartSize は 8,000 バイト、アップロード URI の数は 5 だとします。以下の手順を実行します。

• 最初のアップロード URI を使用して、バイナリの最初の 8,000 バイトをアップロードします。
• 2 番目のアップロード URI を使用して、バイナリの 2 番目の 8,000 バイトをアップロードします。
• 3 番目のアップロード URI を使用して、バイナリの最後の 4,000 バイトをアップロードします。これが最後のパーツなので、minPartSize.以上の大きさにする必要はありません。
• 最後の 2 つのアップロード URI を使用する必要はありません。無視して構いません。

よくあるエラーは、API で提供されるアップロード URI の数に基づいて各部分のサイズを計算することです。API 契約では、この方法が機能するとは保証されず、実際には、minPartSize と maxPartSize の範囲外のパーツサイズになる場合があります。その結果、バイナリのアップロードに失敗する可能性があります。

繰り返しますが、最も簡単で安全な方法は、単に maxPartSize.と同じサイズのパーツを使用することです。

アップロードに成功した場合、サーバーは各リクエストへの応答として 201 ステータスコードを返します。

アップロードの完了

バイナリファイルのすべての部分がアップロードされたら、開始データから提供される完全な URI に HTTP POST リクエストを送信します。リクエスト本文のコンテンツタイプは、次のフィールドを含んだ application/x-www-form-urlencoded 形式のデータにする必要があります。

開始プロセスと同様に、完了リクエストデータには、複数のファイルに関する情報が含まれる場合があります。

バイナリのアップロードプロセスは、ファイルの完了 URL が呼び出されるまで実行されません。アセットは、アップロードプロセスの完了後に処理されます。アセットのバイナリファイルが完全にアップロードされても、アップロードプロセスが完了していなければ、処理は開始しません。アップロードが正常に完了した場合、サーバーは応答として 200 ステータスコードを返します。

オープンソースアップロードライブラリ

アップロードアルゴリズムの詳細を調べたり、独自のアップロードスクリプトやツールを作成する場合に役立つように、アドビでは、次のオープンソースライブラリおよびツールを提供しています。

• オープンソース aem-upload ライブラリ。
• オープンソースコマンドラインツール。

非推奨（廃止予定）のアセットアップロード API

新しいアップロード方法は、Adobe Experience Manager as a Cloud Service の場合のみサポートされます。Adobe Experience Manager 6.5 の API は非推奨（廃止予定）となりました。アセットやレンディションのアップロードまたは更新（あらゆるバイナリアップロード）に関連するメソッドは、次の API で非推奨（廃止予定）となりました。

• Adobe Experience Manager Assets HTTP API
• AssetManagerJava API（AssetManager.createAsset(..)、AssetManager.createAssetForBinary(..)、AssetManager.getAssetForBinary(..)、AssetManager.removeAssetForBinary(..)、AssetManager.createOrUpdateAsset(..)、AssetManager.createOrReplaceAsset(..) など）

アセット処理ワークフローとアセット後処理ワークフロー

Experience Manager でのアセット処理は、アセットマイクロサービスを使用する​処理プロファイル​設定に基づいて行われます。処理には、開発者用の拡張機能は必要ありません。

後処理ワークフローの設定には、カスタム手順を指定した標準ワークフローを使用します。

後処理ワークフローでのワークフローステップのサポート

Adobe Experience Manager の以前のバージョンからアップグレードした場合は、アセットマイクロサービスを使用してアセットを処理できます。クラウドネイティブのアセットマイクロサービスは、設定と使用が簡単です。以前のバージョンの DAM アセットの更新ワークフローで使用されるワークフロー手順の一部はサポートされていません。サポートされているクラスについて詳しくは、Java API リファレンスか Javadoc を参照してください。

次のテクニカルワークフローモデルは、アセットマイクロサービスに置き換わっているか、サポートされていません。

• com.day.cq.dam.cameraraw.process.CameraRawHandlingProcess
• com.day.cq.dam.core.process.CommandLineProcess
• com.day.cq.dam.pdfrasterizer.process.PdfRasterizerHandlingProcess
• com.day.cq.dam.core.process.AddPropertyWorkflowProcess
• com.day.cq.dam.core.process.CreateSubAssetsProcess
• com.day.cq.dam.core.process.DownloadAssetProcess
• com.day.cq.dam.word.process.ExtractImagesProcess
• com.day.cq.dam.word.process.ExtractPlainProcess
• com.day.cq.dam.ids.impl.process.IDSJobProcess
• com.day.cq.dam.indd.process.INDDMediaExtractProcess
• com.day.cq.dam.indd.process.INDDPageExtractProcess
• com.day.cq.dam.core.impl.lightbox.LightboxUpdateAssetProcess
• com.day.cq.dam.pim.impl.sourcing.upload.process.ProductAssetsUploadProcess
• com.day.cq.dam.core.process.SendDownloadAssetEmailProcess
• com.day.cq.dam.similaritysearch.internal.workflow.smarttags.StartTrainingProcess
• com.day.cq.dam.similaritysearch.internal.workflow.smarttags.TransferTrainingDataProcess
• com.day.cq.dam.switchengine.process.SwitchEngineHandlingProcess
• com.day.cq.dam.core.process.GateKeeperProcess
• com.day.cq.dam.s7dam.common.process.DMEncodeVideoWorkflowCompletedProcess
• com.day.cq.dam.core.process.DeleteImagePreviewProcess
• com.day.cq.dam.video.FFMpegTranscodeProcess
• com.day.cq.dam.core.process.ThumbnailProcess
• com.day.cq.dam.video.FFMpegThumbnailProcess
• com.day.cq.dam.core.process.CreateWebEnabledImageProcess
• com.day.cq.dam.core.process.CreatePdfPreviewProcess
• com.day.cq.dam.s7dam.common.process.VideoUserUploadedThumbnailProcess
• com.day.cq.dam.s7dam.common.process.VideoThumbnailDownloadProcess
• com.day.cq.dam.s7dam.common.process.VideoProxyServiceProcess
• com.day.cq.dam.scene7.impl.process.Scene7UploadProcess
• com.day.cq.dam.s7dam.common.process.S7VideoThumbnailProcess
• com.day.cq.dam.core.process.MetadataProcessorProcess
• com.day.cq.dam.core.process.AssetOffloadingProcess
• com.adobe.cq.dam.dm.process.workflow.DMImageProcess

関連情報

• アセットを翻訳
• Assets HTTP API
• AEM Assets as a Cloud Service でサポートされているファイル形式
• アセットを検索
• 接続されたアセット
• アセットレポート
• メタデータスキーマ
• アセットをダウンロード
• メタデータを管理
• 検索ファセット
• コレクションを管理
• メタデータの一括読み込み