Assets HTTP API には次の API が含まれます。
AEM Assets HTTP API の現在の実装は REST です。
Adobe Experience Manager(AEM) Assets REST APIを使用すると、開発者はHTTP API経由で(AEMに保存された)コンテンツに、CRUD操作(作成、読み取り、更新、削除)経由で直接アクセスできます。
この API では、コンテンツサービスを JavaScript フロントエンドアプリケーションに提供することで、AEM をヘッドレス CMS(コンテンツ管理システム)として動作させることができます。または、HTTP リクエストを実行して JSON 応答を処理できる他のどのようなアプリケーションにもすることができます。
例えば、単一ページアプリケーション(SPA)では、フレームワークベースかカスタムかを問わず、HTTP API 経由で提供されるコンテンツ(多くの場合 JSON 形式)が必要です。
AEMコアコンポーネントは、この目的で必要な読み取り操作とJSON出力をカスタマイズできる、非常に包括的で柔軟性とカスタマイズ性に優れたAPIを提供しますが、専用のAEMテンプレートに基づく(API)ページでホストする必要があるAEM WCM(Webコンテンツ管理)ノウハウを実装する必要があります。 すべての SPA 開発組織が、こうしたリソースにアクセスできるわけではありません。
これが可能なのは、Assets REST API が使用できる場合です。この場合は、アセット(画像やコンテンツフラグメントなど)に直接アクセスでき、その際に、ページにアセットを埋め込んでからコンテンツをシリアル化 JSON 形式で配信する必要はありません(Assets REST API からの JSON 出力をカスタマイズできないことに注意してください)。また、Assets REST API を使用すると、アセット、コンテンツフラグメント、フォルダーの新規作成、更新、削除のいずれかの操作でコンテンツを変更することもできます。
Assets REST API は、
HATEOAS の原則に従っています。
SIREN 形式を実装しています。
Assets REST API は、最近の AEM バージョンの標準インストールで使用できます。
Assets REST API を使用すると、AEM インスタンス内に格納されたアセットに REST 形式でアクセスすることができます。/api/assets
エンドポイントを使用しており、アクセスするにはアセットのパス(先頭の /content/dam
を除く)が必要です。
実行する操作は HTTP メソッドで決まります。
リクエスト本文または URL パラメーターは、これらの操作の一部を設定するために使用できます。例えば、フォルダーまたはアセットを POST リクエストで作成するように定義できます。
サポートされているリクエストの正確な形式は、『API リファレンス』ドキュメントで定義されています。
すべてのリクエストはアトミックです。
つまり、後続の(write
)リクエストを結合して、単一のエンティティとして成功または失敗する単一のトランザクションにすることはできません。
項目 | Assets REST API |
AEM コンポーネント (Sling モデルを使用するコンポーネント) |
サポートされている使用例 | 汎用。 | 単一ページアプリケーション(SPA)またはその他の任意の(コンテンツ利用)コンテキストにおける使用に最適化されています。 レイアウト情報を含むこともできます。 |
サポートされている操作 | 作成、読み取り、更新、削除。 エンティティタイプに応じて、その他の操作も可能です。 |
読み取り専用。 |
アクセス | 直接アクセスできます。
例えば、 |
AEM ページ上の AEM コンポーネントを通じて参照する必要があります。
URLの例を次に示します。 |
セキュリティ | 複数のオプションが可能です。 OAuth が推奨されます。標準セットアップとは別に設定できます。 |
AEM の標準セットアップを使用します。 |
アーキテクチャに関する補足 | 書き込みアクセスは通常、オーサーインスタンスを対象にします。 読み取りはパブリッシュインスタンスを対象にする場合もあります。 |
このアプローチは読み取り専用なので、通常はパブリッシュインスタンスに使用されます。 |
出力 | JSON ベースの SIREN 出力:詳細ながら強力です。コンテンツ内のナビゲーションが可能です。 | JSON ベースの独自出力。Sling モデルを通じて設定可能です。コンテンツ構造のナビゲーションは実装が困難です(ただし、必ずしも不可能ではありません)。 |
特定の認証要件がない環境で Assets REST API が使用される場合は、AEM の CORS フィルターを正しく設定する必要があります。
詳しくは、次のセクションを参照してください。
特定の認証要件がある環境では、OAuth を推奨します。
コンテンツフラグメントは特定のアセットタイプです。](/docs/experience-manager-65/assets/fragments/content-fragments.html?lang=ja)コンテンツフラグメントの操作[を参照してください。
API を通じて使用できる機能について詳しくは、以下を参照してください。
Assets REST API では、URL パラメーターを介して(GET リクエストの)ページングをサポートしています。
offset
- 取得する最初の(子)エンティティの数limit
- 返されるエンティティの最大数応答には、SIREN 出力の properties
セクションの一部としてページング情報が含まれます。この srn:paging
プロパティには、リクエストで指定されている、(子)エンティティの総数(total
)、オフセット(offset
)および制限(limit
)が含まれています。
ページングは通常、コンテナエンティティ(つまり、レンディションのあるフォルダーやアセット)に適用されます。要求されたエンティティの子に関係するからです。
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
フォルダーは、アセットやその他のフォルダーのコンテナとして機能します。AEM コンテンツリポジトリの構造を反映しています。
Assets REST API は、フォルダーのプロパティ(名前、タイトルなど)へのアクセスを公開します。アセットは、フォルダーの子エンティティとして公開されます。
アセットタイプによっては、それぞれの子エンティティを定義するすべてのプロパティが、子エンティティのリストに既に含まれている場合があります。または、この子エンティティリストのエンティティに対して、一部のプロパティのみ公開される場合もあります。
アセットが要求されると、アセットのメタデータ(タイトルや名前など、それぞれのアセットスキーマで定義される情報)が応答で返されます。
アセットのバイナリデータは、content
タイプの SIREN リンクとして公開されます(rel attribute
とも呼ばれます)。
アセットには複数のレンディションを含めることができます。通常、これらは子エンティティとして公開されます。ただし、サムネールレンディションは例外です。これは、thumbnail
タイプ(rel="thumbnail"
)のリンクとして公開されます。
コンテンツフラグメントは特殊なタイプのアセットです。コンテンツフラグメントを使用すれば、テキスト、数値、日付など様々な要素を含む構造化データにアクセスできます。
標準アセット(画像やオーディオなど)との違いがいくつかあるので、それらの処理には追加のルールが適用されます。**
コンテンツフラグメント:
バイナリデータを公開しません。
JSON 出力(properties
プロパティ内)に完全に含まれます。
アトミックと見なされます。つまり、エレメントとバリエーションは、リンクまたは子エンティティとしてではなく、フラグメントのプロパティの一部として公開されます。これにより、フラグメントのペイロードに効率的にアクセスできます。
現在、コンテンツフラグメントの構造を定義するモデルは、HTTP API では公開されません。そのため、コンシューマーは(最低でも)フラグメントのモデルについて理解する必要があります。ただし、ほとんどの情報はペイロードから推測することができます。データタイプなど**は定義の一部だからです。
新しいコンテンツフラグメントを作成するには、(内部リポジトリ)パスを指定する必要があります。
関連コンテンツは現在公開されていません。
使用方法は、特定の使用例以外にも、AEM オーサーを使用するかパブリッシュ環境を使用するかで異なることがあります。
作成はオーサーインスタンスに厳密に結び付けられています(現在は、この API を使用して公開するフラグメントをレプリケートする手段はありません)。
配信は、どちらからも可能です。AEM では、要求されたコンテンツを JSON 形式でのみ提供するからです。
AEM クラウドインスタンス上の Dispatcher 設定により、/api
へのアクセスがブロックされる場合があります。
詳細については、『](/docs/experience-manager-65/assets/extending/assets-api-content-fragments.html?lang=ja#api-reference)API リファレンス[』を参照してください。特に、Adobe Experience Manager Assets API - コンテンツフラグメント。
使用方法は次のとおりです。
GET /{cfParentPath}/{cfName}.json
次に例を示します。
https://localhost:4502/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.json
応答は、コンテンツがコンテンツフラグメントに構造化されたシリアル化 JSON です。参照は参照 URL として配信されます。
次の 2 通りの読み取り操作が可能です。
使用方法は次のとおりです。
POST /{cfParentPath}/{cfName}
本文には、作成するコンテンツフラグメントの JSON 表現を含める必要があります。これには、コンテンツフラグメント要素に設定する必要がある初期コンテンツも含まれます。cq:model
プロパティの設定が必須で、このプロパティが有効なコンテンツフラグメントモデルを指している必要があります。そうしないと、エラーが発生します。また、Content-Type
ヘッダーを追加することも必要です。これは application/json
に設定されます。
使用方法は次のとおりです。
PUT /{cfParentPath}/{cfName}
本文には、特定コンテンツフラグメントの更新内容の JSON 表現を含める必要があります。
これには、コンテンツフラグメントのタイトルや説明、単一のエレメント、またはすべての要素値やメタデータを使用できます。また、更新のための有効なcq:model
プロパティを指定する必要もあります。
使用方法は次のとおりです。
DELETE /{cfParentPath}/{cfName}
次のように、いくつかの制限があります。
バリエーションは書き込みも更新もできません。バリエーションが(更新などの)ペイロードに追加された場合は、無視されます。ただし、このバリエーションは配信(GET
)を通じて提供されます。
コンテンツフラグメントモデルは現在サポートされていません。読み取りも作成もできません。新しいコンテンツフラグメントを作成または既存のコンテンツフラグメントを更新できるようにするには、コンテンツフラグメントモデルの正しいパスがわかっている必要があります。現在のところ、これらの概要を取得するには、管理 UI を使用するしかありません。
参照は無視されます。現時点では、既存のコンテンツフラグメントが参照されているかどうかはチェックされません。したがって、例えば、コンテンツフラグメントを削除すると、それへの参照を含んでいるページで問題が発生する可能性があります。
関連する状況で次のステータスコードが表示されることがあります。
200(OK)
次の場合に返されます。
GET
でコンテンツフラグメントを要求する
PUT
でコンテンツフラグメントを正常に更新する
201(Created)
次の場合に返されます。
POST
でコンテンツフラグメントを正常に作成する404(Not Found)
次の場合に返されます。
500(内部サーバーエラー)
次の場合に返されます。
このエラーステータスと生成されたエラーメッセージ(等幅テキスト)が返される一般的なシナリオの一覧を以下に示します。
親フォルダーが存在しない(POST
でコンテンツフラグメントを作成する場合)
コンテンツフラグメントモデルが指定されていない(null 値)、リソースが null(権限の問題が発生している可能性あり)、リソースが有効なフラグメントテンプレートでない。
No content fragment model specified
Cannot create a resource of given model '/foo/bar/qux'
Cannot adapt the resource '/foo/bar/qux' to a content fragment template
コンテンツフラグメントを作成できなかった(アクセス権限の問題が発生している可能性がある)。
Could not create content fragment
タイトルや説明を更新できなかった。
Could not set value on content fragment
メタデータを設定できなかった。
Could not set metadata on content fragment
コンテンツ要素が見つからなかったか更新できなかった
Could not update content element
Could not update fragment data of element
通常、詳細なエラーメッセージは次のように返されます。
{
"class": "core/response",
"properties": {
"path": "/api/assets/foo/bar/qux",
"location": "/api/assets/foo/bar/qux.json",
"parentLocation": "/api/assets/foo/bar.json",
"status.code": 500,
"status.message": "...{error message}.."
}
}
詳細な API リファレンスについては、こちらを参照してください。
詳しくは、次のセクションを参照してください。