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 は、すべての操作または一部の操作をサポートしています。

注意

一部のAPIは引き続き存在しますが、アクティブにはサポートされていません（「×」を付けて示します）。これらのAPIは、可能な限り使用しないでください。

サポートレベル	説明
✓	サポート対象
×	サポートされていない。使用しないでください。
-	使用不可

使用例	aem-upload	AEM／Sling／JCR Java API	Asset Compute Service	Assets HTTP API	Sling GET／POST サーブレット	GraphQL （プレビュー）
元のバイナリ
オリジナルを作成	kid	×	-	×	×	-
オリジナルを読む	-	×	kid	kid	kid	-
オリジナルをアップデート	kid	×	kid	×	×	-
オリジナルを削除	-	kid	-	kid	kid	-
オリジナルをコピー	-	kid	-	kid	kid	-
オリジナルを移動	-	kid	-	kid	kid	-
メタデータ
メタデータを作成	-	kid	kid	kid	kid	-
メタデータを読み取り	-	kid	-	kid	kid	-
メタデータを更新	-	kid	kid	kid	kid	-
メタデータを削除	-	kid	kid	kid	kid	-
メタデータをコピー	-	kid	-	kid	kid	-
メタデータを移動	-	kid	-	kid	kid	-
コンテンツフラグメント（CF）
CF を作成	-	kid	-	kid	-	-
CF を読み取り	-	kid	-	kid	-	kid
CF を更新	-	kid	-	kid	-	-
CF を削除	-	kid	-	kid	-	-
CF をコピー	-	kid	-	kid	-	-
CF を移動	-	kid	-	kid	-	-
バージョン
バージョンを作成	kid	kid	-	-	-	-
バージョンを読み取り	-	kid	-	-	-	-
バージョンを削除	-	kid	-	-	-	-
フォルダー
フォルダーを作成	kid	kid	-	kid	-	-
フォルダを読み取り	-	kid	-	kid	-	-
フォルダーを削除	kid	kid	-	kid	-	-
フォルダーをコピー	kid	kid	-	kid	-	-
フォルダーを移動	kid	kid	-	kid	-	-

アセットのアップロード

Experience ManagerにCloud Serviceとして、HTTP APIを使用して、アセットをクラウドストレージに直接アップロードできます。バイナリファイルをアップロードする手順は次のとおりです。

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

直接バイナリアップロードプロトコルの概要

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

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

メモ

この方法を実装するクライアントコードを確認するには、オープンソースの aem-upload ライブラリを参照してください。

アップロードの開始

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

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

バイナリのアップロード

アップロードを開始した場合の出力には、1 つ以上のアップロード URI 値が含まれています。複数の URI を指定した場合、クライアント側でバイナリを複数の部分に分割し、各部分の POST リクエストを各 URI に順に送信します。すべての URI を使用します。各部分のサイズが、開始応答で指定された最小サイズと最大サイズの範囲内に収まっている必要があります。CDN エッジノードを使用すると、要求されたバイナリアップロードを高速化できます。

これを実現するには、API で提供されるアップロード URI の数に基づいて各部分のサイズを計算する方法があります。例えば、バイナリの合計サイズが 20,000 バイトで、アップロード URI の数が 2 だとします。この場合は次の手順に従います。

合計サイズを URI 数で除算して各部分のサイズを計算。20,000 / 2 = 10,000
アップロード URI リストの最初の URI にバイナリの 0～9,999 バイトを POST 送信。
アップロード URI リストの 2 番目の URI にバイナリの 10,000～19,999 バイトを POST 送信。

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

アップロードの完了

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

フィールド	型	必須／未指定	説明
`fileName`	String	必須	アセットの名前（開始データで提供されたもの）。
`mimeType`	文字列	必須	バイナリの HTTP コンテンツタイプ（開始データで提供されたもの）。
`uploadToken`	文字列	必須	バイナリのアップロードトークン（開始データで提供されたもの）。
`createVersion`	Boolean	オプション	これが `True` で、指定した名前のアセットが存在する場合、Adobe Experience Manager はアセットの新しいバージョンを作成します。
`versionLabel`	文字列	オプション	新しいバージョンが作成される場合、アセットの新しいバージョンに関連付けられるラベル。
`versionComment`	文字列	オプション	新しいバージョンが作成される場合、そのバージョンに関連付けられたコメント。
`replace`	ブール値	オプション	これが `True` で指定した名前のアセットが存在する場合、Adobe Experience Manager はそのアセットを削除し、再作成します。

メモ

アセットが存在し、createVersion も replace も指定されていない場合、Adobe Experience Manager はアセットの現在のバージョンを新しいバイナリで更新します。

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

バイナリのアップロードプロセスは、ファイルの完了 URL が呼び出されるまで実行されません。アセットは、アップロードプロセスの完了後に処理されます。アセットのバイナリファイルが完全にアップロードされても、アップロードプロセスが完了していなければ、処理は開始しません。

成功した場合、サーバーは応答として 200 ステータスコードを返します。

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

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

非推奨（廃止予定）のアセットアップロード 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(..) など）

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

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

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

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

Experience Manager as a Cloud Service でサポートされているワークフローステップは次のとおりです。

com.day.cq.dam.similaritysearch.internal.workflow.process.AutoTagAssetProcess
com.day.cq.dam.core.impl.process.CreateAssetLanguageCopyProcess
com.day.cq.wcm.workflow.process.CreateVersionProcess
com.day.cq.dam.similaritysearch.internal.workflow.smarttags.StartTrainingProcess
com.day.cq.dam.similaritysearch.internal.workflow.smarttags.TransferTrainingDataProcess
com.day.cq.dam.core.impl.process.TranslateAssetLanguageCopyProcess
com.day.cq.dam.core.impl.process.UpdateAssetLanguageCopyProcess
com.adobe.cq.workflow.replication.impl.ReplicationWorkflowProcess
com.day.cq.dam.core.impl.process.DamUpdateAssetWorkflowCompletedProcess