AEM Assets HTTP API でのコンテンツフラグメントのサポート

概要

AEM ヘッドレス配信機能の重要な部分である、Assets HTTP API でのコンテンツフラグメントのサポートについて学びます。

Assets REST API を使用すると、Adobe Experience Manager as a Cloud Service の開発者は、HTTP API 経由で CRUD 操作（作成、読み取り、更新、削除）を介して、（AEM に保存された）コンテンツに直接アクセスできます。

この API では、コンテンツサービスを JavaScript フロントエンドアプリケーションに提供することで、Adobe Experience Manager as a Cloud Service をヘッドレス CMS（コンテンツ管理システム）として動作させることができます。または、HTTP リクエストを実行して JSON 応答を処理できるその他のアプリケーション。

例えば、単一ページアプリケーション（SPA）では、フレームワークベースかカスタムかを問わず、HTTP API 経由で提供されるコンテンツ（多くの場合 JSON 形式）が必要です。

While AEMコアコンポーネント この目的で必要な読み取り操作と、JSON 出力をカスタマイズできる API には、実装にAEM WCM(Web Content Management) のノウハウが必要です。 これは、専用のAEMテンプレートに基づくページでホストする必要があるからです。 すべての SPA 開発組織が、こうした知識にアクセスできるわけではありません。

これが可能なのは、Assets REST API が使用できる場合です。この場合は、アセット（画像やコンテンツフラグメントなど）に直接アクセスでき、その際に、ページにアセットを埋め込んでからコンテンツをシリアル化 JSON 形式で配信する必要はありません

また、Assets REST API を使用すると、アセット、コンテンツフラグメント、フォルダーの新規作成、更新、削除のいずれかの操作でコンテンツを変更することもできます。

Assets REST API は、

• HATEOAS の原則に従っています。

• SIREN 形式を実装しています。

前提条件

Assets REST API は、最新の Adobe Experience Manager as a Cloud Service バージョンの標準インストールで利用できます。

主要な概念

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 をリクエストします。

実行する操作は HTTP メソッドで決まります。

• GET：アセットまたはフォルダーの JSON 表現を取得します
• POST：新しいアセットまたはフォルダーを作成します
• PUT：アセットまたはフォルダーのプロパティを更新します
• DELETE：アセットまたはフォルダーを削除します

サポートされているリクエストの正確な形式は、API リファレンスドキュメントで定義されています。

トランザクション動作

すべてのリクエストはアトミックです。

つまり、後続の（write）リクエストを結合して、単一のエンティティとして成功または失敗する単一のトランザクションにすることはできません。

AEM（Assets）REST API と AEM コンポーネントの比較

セキュリティ

特定の認証要件がない環境で Assets REST API が使用される場合は、AEM の CORS フィルターを正しく設定する必要があります。

特定の認証要件がある環境では、OAuth を推奨します。

使用可能な機能

コンテンツフラグメントは特定のアセットタイプです。コンテンツフラグメントの操作を参照してください。

API を通じて使用できる機能について詳しくは、以下を参照してください。

• Assets REST 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 は、フォルダーのプロパティへのアクセスを公開します。 例えば、名前やタイトルなどです。 アセットは、フォルダーの子エンティティ、およびサブフォルダーとして公開されます。

Assets

アセットが要求されると、アセットのメタデータ（タイトルや名前など、それぞれのアセットスキーマで定義される情報）が応答で返されます。

アセットのバイナリデータは、content タイプの SIREN リンクとして公開されます。

アセットには複数のレンディションを含めることができます。通常、これらは子エンティティとして公開されます。ただし、サムネールレンディションは例外です。これは、thumbnail タイプ（rel="thumbnail"）のリンクとして公開されます。

コンテンツフラグメント

コンテンツフラグメントは特殊なタイプのアセットです。テキスト、数値、日付などの構造化データにアクセスするために使用できます。

標準​アセット（画像やオーディオなど）との違いがいくつかあるので、それらの処理には追加のルールが適用されます。

表現

コンテンツフラグメント：

• バイナリデータを公開しません。

• JSON 出力（properties プロパティ内）に完全に含まれます。

• 原子とも考えられています。 また、アトミックと見なされます。つまり、エレメントとバリエーションは、リンクまたは子エンティティとしてではなく、フラグメントのプロパティの一部として公開されます。これにより、フラグメントのペイロードに効率的にアクセスできます。

コンテンツモデルとコンテンツフラグメント

現在、コンテンツフラグメントの構造を定義するモデルは、HTTP API では公開されません。したがって、 消費者 は、フラグメントのモデルについて（少なくとも 1 つ）把握している必要があります。ほとんどの情報はペイロードから推論できますが、データタイプなどは定義の一部です。

新しいコンテンツフラグメントを作成するには、（内部リポジトリ）モデルのパスを指定する必要があります。

関連コンテンツ

関連コンテンツは現在公開されていません。

使用

使用方法は、特定の使用例以外にも、AEM オーサーを使用するかパブリッシュ環境を使用するかで異なることがあります。

• 作成をオーサーインスタンスに結び付けることを強くお勧めします（現在は、この API を使用して公開するフラグメントをレプリケートする手段はありません）。

• AEM は要求されたコンテンツを JSON 形式でのみ提供するので、どちらからも配信できます。

  • ファイアウォールの背後で動作するメディアライブラリアプリケーションには、AEM オーサーインスタンスからのストレージと配信で十分です。

  • ライブ web 配信の場合は、AEM パブリッシュインスタンスをお勧めします。

制限事項

次のように、いくつかの制限があります。

• コンテンツフラグメントモデルは現在サポートされていません：読み取りも作成もできません。既存のコンテンツフラグメントを作成または更新できるようにするには、開発者がコンテンツフラグメントモデルへの正しいパスを知っている必要があります。 現在のところ、これらの概要を取得するには、管理 UI を使用するしかありません。
• 参照は無視されます。現在、既存のコンテンツフラグメントが参照されているかどうかの確認は行われません。したがって、例えば、コンテンツフラグメントを削除すると、削除されたコンテンツフラグメントへの参照を含んでいるページで問題が発生する可能性があります。
• JSON データ型 JSON データ型​の REST API 出力は、現在、文字列ベースの出力​です。

ステータスコードとエラーメッセージ

関連する状況で次のステータスコードが表示されることがあります。

• 200（OK）

  次の場合に返されます。

  • 次の方法でコンテンツフラグメントを要求する GET
  • 次の方法でコンテンツフラグメントを正常に更新する PUT

• 201（Created）

  次の場合に返されます。

  • 次の方法でコンテンツフラグメントを正常に作成する POST

• 404（Not Found）

  次の場合に返されます。

  • 要求されたコンテンツフラグメントが存在しない

• 500（内部サーバーエラー）

  メモ

  次の場合に返されます。

  • 特定のコードで識別できないエラーが発生した場合
  • 指定されたペイロードが無効な場合

  以下に、このエラーステータスが返される場合の一般的なシナリオと、生成されるエラーメッセージ（等幅）を示します。

  • 親フォルダーが存在しない（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

  通常、詳細なエラーメッセージは次のように返されます。

  {
    "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 リファレンス

詳細な API リファレンスについては、こちらを参照してください。

• Adobe Experience Manager Assets API - コンテンツフラグメント

• Assets HTTP API

  • 使用可能な機能

その他のリソース

詳しくは、次を参照してください。

• Assets HTTP API ドキュメント
• AEM Gem セッション：OAuth