AEM Assets HTTP API でのコンテンツフラグメントのサポート :headding-anchor:content-fragments-support-in-aem-assets-http-api
概要 :headding-anchor:overview
AEM ヘッドレス配信機能の重要な部分である、Assets HTTP API でのコンテンツフラグメントのサポートについて説明します。
- Assets REST API
- コンテンツフラグメントをサポートしています
Assets REST API を使用すると、Adobe Experience Manager のデベロッパーは、HTTP API 経由で CRUD 操作(作成、読み取り、アップデート、削除)を介して、(AEM に格納された)コンテンツにアクセスできます。
この API では、コンテンツサービスを JavaScript フロントエンドアプリケーションに提供することで、Adobe Experience Manager をヘッドレス CMS(コンテンツ管理システム)として動作させることができます。または、HTTP リクエストを実行して JSON 応答を処理できる他のどのようなアプリケーションにもすることができます。
例えば、単一ページアプリケーション(SPA)では、フレームワークベースかカスタムかを問わず、HTTP API 経由で提供されるコンテンツ(多くの場合 JSON 形式)が必要です。
AEM コアコンポーネントは、この目的に必要な読み取り操作を提供できる非常に包括的で柔軟性の高いカスタマイズ可能な API を提供し、その JSON 出力もカスタマイズできますが、実装には AEM WCM(Web コンテンツ管理)のノウハウが必要です。専用の AEM テンプレートに基づいた(API)ページでこれらのコンポーネントをホストする必要があるからです。すべての SPA 開発組織が、こうした知識にアクセスできるわけではありません。
これが可能なのは、Assets REST API が使用できる場合です。この場合は、アセット(画像やコンテンツフラグメントなど)に直接アクセスでき、その際に、ページにアセットを埋め込んでからコンテンツをシリアル化 JSON 形式で配信する必要はありません
また、Assets REST API を使用すると、アセット、コンテンツフラグメント、フォルダーの新規作成、更新、削除のいずれかの操作でコンテンツを変更することもできます。
Assets REST API は、
-
HATEOAS の原則に従っています。
-
SIREN 形式を実装しています。
前提条件 :headding-anchor:prerequisites
Assets REST API は、最近の AEM バージョンの標準インストールで使用できます。
主要な概念 :headding-anchor:key-concepts
Assets REST API を使用すると、AEM インスタンス内に格納されたアセットに REST 形式でアクセスすることができます。
/api/assets
エンドポイントを使用しており、アクセスするにはアセットのパス(先頭の /content/dam
を除く)が必要です。
- つまり、次の場所のアセットにアクセスするには
/content/dam/path/to/asset
- 次のリクエストが必要です。
/api/assets/path/to/asset
例えば、/content/dam/wknd/en/adventures/cycling-tuscany
にアクセスするには、/api/assets/wknd/en/adventures/cycling-tuscany.json
をリクエストします。
/api/assets
は.model
セレクターを使用する 必要はありません。/content/path/to/page
は.model
セレクターを使用する 必要があります。
実行する操作は HTTP メソッドで決まります。
- GET:アセットまたはフォルダーの JSON 表現を取得します
- POST:新しいアセットまたはフォルダーを作成します
- PUT:アセットまたはフォルダーのプロパティを更新します
- DELETE:アセットまたはフォルダーを削除します
サポートされているリクエストの正確な形式は、API リファレンスドキュメントで定義されています。
トランザクション動作 :headding-anchor:transactional-behavior
すべてのリクエストはアトミックです。
つまり、後続の(write
)リクエストを結合して、単一のエンティティとして成功または失敗する単一のトランザクションにすることはできません。
AEM(Assets)REST API と AEM コンポーネントの比較 :headding-anchor:aem-assets-rest-api-versus-aem-components
(Sling モデルを使用するコンポーネント)
単一ページアプリケーション(SPA)またはその他の任意の(コンテンツ利用)コンテキストにおける使用に最適化されています。
レイアウト情報を含めることもできます。
作成、読み取り、更新、削除。
エンティティタイプに応じて、その他の操作も可能です。
直接アクセスできます。
/api/assets
エンドポイントを使用し、(リポジトリー内の)/content/dam
にマッピングします。
パスの例を次に示します。 /api/assets/wknd/en/adventures/cycling-tuscany.json
AEM ページ上の AEM コンポーネントを通じて参照する必要があります。
.model
セレクターを使用して JSON 表現を作成します。
パスの例を次に示します。/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
複数のオプションを使用できます。
OAuth が推奨されます。標準セットアップとは別に設定できます。
書き込みアクセスは通常、オーサーインスタンスを対象にします。
読み取りはパブリッシュインスタンスを対象にする場合もあります。
セキュリティ :headding-anchor:security
特定の認証要件がない環境で Assets REST API が使用される場合は、AEM の CORS フィルターを正しく設定する必要があります。
特定の認証要件がある環境では、OAuth を推奨します。
使用可能な機能 :headding-anchor:available-features
コンテンツフラグメントは特定のアセットタイプです。コンテンツフラグメントの操作を参照してください。
API を通じて使用できる機能について詳しくは、以下を参照してください。
- Assets REST API
- エンティティタイプ。(コンテンツフラグメントに関連した)サポートされる各タイプに固有の機能について説明します。
ページング :headding-anchor:paging
Assets REST API では、URL パラメーターを介して(GET リクエストの)ページングをサポートしています。
offset
- 取得する最初の(子)エンティティの数limit
- 返されるエンティティの最大数
応答には、SIREN 出力の properties
セクションの一部としてページング情報が含まれます。この srn:paging
プロパティには、リクエストで指定されている、(子)エンティティの総数(total
)、オフセット(offset
)および制限(limit
)が含まれています。
例:ページング :headding-anchor:example-paging
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
エンティティタイプ :headding-anchor:entity-types
フォルダー :headding-anchor:folders
フォルダーは、アセットや他のフォルダーのコンテナとして機能します。 AEM コンテンツリポジトリーの構造を反映しています。
Assets REST API は、フォルダーのプロパティ(名前、タイトルなど)へのアクセスを公開します。アセットは、フォルダーの子エンティティ、およびサブフォルダーとして公開されます。
Assets :headding-anchor:assets
アセットが要求されると、アセットのメタデータ(タイトルや名前など、それぞれのアセットスキーマで定義される情報)が応答で返されます。
アセットのバイナリデータは、content
タイプの SIREN リンクとして公開されます。
アセットには複数のレンディションを含めることができます。通常、これらは子エンティティとして公開されます。ただし、サムネールレンディションは例外です。これは、thumbnail
タイプ(rel="thumbnail"
)のリンクとして公開されます。
コンテンツフラグメント :headding-anchor:content-fragments
コンテンツフラグメントは特殊なタイプのアセットです。テキスト、数値、日付などの構造化データにアクセスするために使用できます。
標準 アセット(画像やオーディオなど)との違いがいくつかあるので、それらの処理には追加のルールが適用されます。
表現 :headding-anchor:representation
コンテンツフラグメント:
-
バイナリデータを公開しません。
-
JSON 出力(
properties
プロパティ内)に完全に含まれます。 -
また、アトミックと見なされます。つまり、エレメントとバリエーションは、リンクまたは子エンティティとしてではなく、フラグメントのプロパティの一部として公開されます。これにより、フラグメントのペイロードに効率的にアクセスできます。
コンテンツモデルとコンテンツフラグメント :headding-anchor:content-models-and-content-fragments
現在、コンテンツフラグメントの構造を定義するモデルは、HTTP API では公開されません。そのため、コンシューマー は(最低でも)フラグメントのモデルについて理解する必are part of the definition.要があります。ただし、ほとんどの情報は、ペイロードから推測できます。データタイプなどは定義の一部だからです。
新しいコンテンツフラグメントを作成するには、(内部リポジトリ)モデルのパスを指定する必要があります。
関連コンテンツ :headding-anchor:associated-content
関連コンテンツは現在公開されていません。
使用 :headding-anchor:using
使用方法は、特定の使用例以外にも、AEM オーサー環境を使用するかパブリッシュ環境を使用するかで異なることがあります。
-
作成をオーサーインスタンスに結び付けることを強くお勧めします(現在は、この API を使用して公開するフラグメントをレプリケートする手段はありません)。
-
AEM は要求されたコンテンツを JSON 形式でのみ提供するので、どちらからも配信できます。
-
ファイアウォールの背後で動作するメディアライブラリアプリケーションには、AEM オーサーインスタンスからのストレージと配信で十分です。
-
ライブ web 配信の場合は、AEM パブリッシュインスタンスをお勧めします。
-
/api
へのアクセスがブロックされる場合があります。読み取り/配信 :headding-anchor:read-delivery
使用方法は次のとおりです。
GET /{cfParentPath}/{cfName}.json
次に例を示します。
http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json
応答は、コンテンツがコンテンツフラグメントに構造化されたシリアル化 JSON です。参照は参照 URL として配信されます。
次の 2 通りの読み取り操作が可能です。
- 特定のコンテンツフラグメントをパスで読み取る。この場合は、コンテンツフラグメントの JSON 表現が返されます。
- コンテンツフラグメントのフォルダーをパスで読み取る。この場合は、フォルダー内のすべてのコンテンツフラグメントの JSON 表現が返されます。
作成 :headding-anchor:create
使用方法は次のとおりです。
POST /{cfParentPath}/{cfName}
本文には、作成するコンテンツフラグメントの JSON 表現を含める必要があります。これには、コンテンツフラグメント要素に設定する必要がある初期コンテンツも含まれます。cq:model
プロパティの設定が必須で、このプロパティが有効なコンテンツフラグメントモデルを指している必要があります。そうしないと、エラーが発生します。また、Content-Type
ヘッダーを追加することも必要です。これは application/json
に設定されます。
アップデート :headding-anchor:update
使用方法は次のとおりです。
PUT /{cfParentPath}/{cfName}
本文には、特定コンテンツフラグメントの更新内容の JSON 表現を含める必要があります。
これには、コンテンツフラグメントのタイトルや説明、単一のエレメント、またはすべての要素値やメタデータを使用できます。
削除 :headding-anchor:delete
使用方法は次のとおりです。
DELETE /{cfParentPath}/{cfName}
制限事項 :headding-anchor:limitations
次のように、いくつかの制限があります。
- コンテンツフラグメントモデルは現在サポートされていません:読み取りも作成もできません。コンテンツフラグメントの作成または既存のコンテンツフラグメントの更新を行えるようにするには、開発者はコンテンツフラグメントモデルへの正しいパスを知っている必要があります。現在のところ、これらの概要を取得するには、管理 UI を使用するしかありません。
- 参照は無視されます。現在、既存のコンテンツフラグメントが参照されているかどうかの確認は行われません。したがって、例えば、コンテンツフラグメントを削除すると、削除されたコンテンツフラグメントへの参照を含んでいるページで問題が発生する可能性があります。
- JSON データ型 JSON データ型 の REST API 出力は、現在、文字列ベースの出力 です。
ステータスコードとエラーメッセージ :headding-anchor:status-codes-and-error-messages
関連する状況で次のステータスコードが表示されることがあります。
-
200 (OK)
は次の場合に返されます。GET
でコンテンツフラグメントを要求するPUT
でコンテンツフラグメントを正常に更新する
-
201(作成済み)
は次の場合に返されます。POST
でコンテンツフラグメントを正常に作成する
-
404(見つかりません)
次の場合に返されます。- 要求されたコンテンツフラグメントが存在しない
-
500(内部サーバーエラー)
note note NOTE 次の場合に返されます。 - 特定のコードで識別できないエラーが発生した場合
- 指定されたペイロードが無効な場合
以下に、このエラーステータスが返される場合の一般的なシナリオと、生成されるエラーメッセージ(等幅)を示します。
-
親フォルダーが存在しない(
POST
でコンテンツフラグメントを作成する場合) -
コンテンツフラグメントモデルが指定されていない(cq:model が見つからない)、読み取れない(パスが無効か権限の問題が原因)、または有効なフラグメントモデルがありません。
No content fragment model specified
Cannot create a resource of given model '/foo/bar/qux'
-
コンテンツフラグメントを作成できなかった(アクセス権限の問題が発生している可能性がある)。
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
通常、詳細なエラーメッセージは次のように返されます。
code language-xml { "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 リファレンス :headding-anchor:api-reference
詳細な API リファレンスについては、こちらを参照してください。
その他のリソース :headding-anchor:additional-resources
詳しくは、次のセクションを参照してください。