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

概要

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 メソッドで決まります。

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

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

トランザクション動作

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

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

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

項目	Assets REST API	AEM コンポーネント （Sling モデルを使用するコンポーネント）
サポートされている使用例	汎用。	単一ページアプリケーション（SPA）またはその他の任意の（コンテンツ利用）コンテキストにおける使用に最適化されています。 レイアウト情報を含むこともできます。
サポートされている操作	作成、読み取り、更新、削除。 エンティティタイプに応じて、その他の操作も可能です。	読み取り専用。
アクセス	直接アクセスできます。 /api/assets エンドポイントを使用し、（リポジトリ内の）/content/dam にマッピングします。 例えば、 /content/dam/we-retail/en/experiences/arctic-surfing-in-lofoten リクエストにアクセスするには： /api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.model.json	AEM ページ上の AEM コンポーネントを通じて参照する必要があります。 .model セレクターを使用して JSON 表現を作成します。 URLの例を次に示します。 https://localhost:4502/content/we-retail/language-masters/en/experience/arctic-surfing-in-lofoten.model.json
セキュリティ	複数のオプションが可能です。 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 の使用可能な機能
• エンティティタイプ

ページング

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 リンクとして公開されます（rel attribute とも呼ばれます）。

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

コンテンツフラグメント

コンテンツフラグメントは特殊なタイプのアセットです。コンテンツフラグメントを使用すれば、テキスト、数値、日付など様々な要素を含む構造化データにアクセスできます。

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

表現

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

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

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

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

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

現在、コンテンツフラグメントの構造を定義するモデルは、HTTP API では公開されません。そのため、コンシューマーは（最低でも）フラグメントのモデルについて理解する必要があります。ただし、ほとんどの情報はペイロードから推測することができます。データタイプなど​**​は定義の一部だからです。

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

関連コンテンツ

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

使用

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

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

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

  • ファイアウォールの背後で動作するメディアライブラリアプリケーションには、AEM オーサーインスタンスからの格納と配信で十分です。
  • ライブ Web 配信の場合は、AEM パブリッシュインスタンスをお勧めします。

読み取り／配信

使用方法は次のとおりです。

GET /{cfParentPath}/{cfName}.json

次に例を示します。

https://localhost:4502/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.json

応答は、コンテンツがコンテンツフラグメントに構造化されたシリアル化 JSON です。参照は参照 URL として配信されます。

次の 2 通りの読み取り操作が可能です。

• 特定のコンテンツフラグメントをパスで読み取る。この場合は、コンテンツフラグメントの JSON 表現が返されます。
• コンテンツフラグメントのフォルダーをパスで読み取る。この場合は、フォルダー内のすべてのコンテンツフラグメントの JSON 表現が返されます。

作成

使用方法は次のとおりです。

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

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

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

• Assets HTTP API

  • 使用可能な機能

その他のリソース

詳しくは、次のセクションを参照してください。

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