AEM Assets HTTP API 中的内容片段支持

概述

Adobe Experience Manager(AEM) Assets REST API允许开发人员通过CRUD操作（创建、读取、更新、删除）直接通过HTTP API访问内容(存储在AEM中)。

API允许您通过向JavaScript前端应用程序提供内容服务，将AEM作为无外设CMS(内容管理系统)进行操作。 或可以执行HTTP请求并处理JSON响应的任何其他应用程序。

例如，单页应用程序(SPA)（基于框架或自定义）需要通过HTTP API提供的内容，通常采用JSON格式。

虽然AEM核心组件提供了一个非常全面、灵活且可自定义的API，可为此目的提供所需的读取操作，并且其JSON输出可进行自定义，但它们确实需要AEM WCM(Web内容管理)专门技术来实现，因为它们必须在基于专用AEM模板的(API)页面中托管。 并非每个SPA开发组织都有权访问此类资源。

此时，可以使用资产REST API。 它允许开发人员直接访问资产（例如图像和内容片段），而无需先将资产嵌入页面，然后以序列化JSON格式提供其内容。 （请注意，无法从Assets REST API自定义JSON输出）。 Assets REST API还允许开发人员通过创建新资产、更新或删除现有资产、内容片段和文件夹来修改内容。

资产REST API:

• 遵循HATEOAS原则

• 实现SIREN格式

前提条件

Assets REST API可用于最新AEM版本的每次现成安装。

重要概念

资产REST API优惠对存储在AEM实例中的资产进行REST样式访问。 它使用/api/assets端点，并需要资产的路径才能访问它（没有前导/content/dam）。

HTTP方法确定要执行的操作：

• GET — 检索资产或文件夹的JSON表示形式
• POST — 创建新资产或文件夹
• PUT — 更新资产或文件夹的属性
• DELETE — 删除资产或文件夹

API参考文档中定义了支持请求的确切格式。

事务行为

所有请求都是原子的。

这意味着后续(write)请求不能合并到单个事务中，该事务可能作为单个实体成功或失败。

AEM(Assets)REST API与AEM组件

安全

如果在环境中使用资产REST API时没有特定的身份验证要求，则需要正确配置AEM CORS筛选器。

在具有特定身份验证要求的环境中，建议使用OAuth。

可用功能

内容片段是资产的特定类型，请参阅使用内容片段。

有关通过API提供的功能的更多信息，请参阅：

• 资 产REST API的可用功能
• 实体类型

分页

资产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内容存储库的结构。

资产REST API公开了对文件夹属性的访问权限；例如，其名称、标题等。 资产会作为文件夹的子实体公开。

资产

如果请求资产，响应将返回其元数据；，如标题、名称和由各个资产模式定义的其他信息。

资产的二进制数据会作为content类型（也称为rel attribute）的SIREN链路公开。

资产可以有多个演绎版。 它们通常作为子实体公开，一个例外是缩略图再现，它作为类型thumbnail(rel="thumbnail")的链接公开。

内容片段

内容片段是一种特殊的资产类型。 它们可用于访问结构化数据，如文本、数字、日期等。

由于​standard​资产（如图像或音频）存在若干差异，因此处理这些资产时会应用一些其他规则。

表示

内容片段：

• 请勿公开任何二进制数据。

• 完全包含在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提供。

有两种读取操作：

• 按路径读取特定内容片段，这将返回内容片段的JSON表示形式。
• 按路径读取内容片段的文件夹：这将返回文件夹中所有内容片段的JSON表示形式。

创建

使用方式：

POST /{cfParentPath}/{cfName}

主体必须包含要创建的内容片段的JSON表示形式，包括应在内容片段元素上设置的任何初始内容。 必须设置cq:model属性，并且必须指向有效的内容片段模型。 否则将导致错误。 还必须添加一个设置为application/json的标题Content-Type。

更新

使用方式为

PUT /{cfParentPath}/{cfName}

主体必须包含要为给定内容片段更新的内容的JSON表示形式。

这只能是内容片段、单个元素或所有元素值和/或元数据的标题或描述。 还必须为更新提供有效的cq:model属性。

删除

使用方式：

DELETE /{cfParentPath}/{cfName}

限制

存在一些限制：

• 无法编写和更新变量。 如果将这些变量添加到有效负荷（例如，用于更新），则将忽略它们。但是，变体将通过投放(GET)提供。

• 当前不支持内容片段模型:无法读取或创建。要能够创建新内容片段或更新现有内容片段，开发人员必须知道指向内容片段模型的正确路径。 目前，只有通过管理UI才能获得这些内容的概述。

• 将忽略引用。当前，不检查是否引用了现有内容片段。 因此，例如，删除内容片段可能会在包含引用的页面上导致问题。

状态代码和错误消息

在相关情况下可以看到以下状态代码：

• 200（确定）

  返回时间：

  • 通过GET请求内容片段

  • 通过PUT成功更新内容片段

• 201（已创建）

  返回时间：

  • 通过POST成功创建内容片段

• 404（未找到）

  返回时间：

  • 请求的内容片段不存在

• 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 — 内容片段

• 资产 HTTP API

  • 可用功能

其他资源

有关更多信息，请参阅：

• 资产HTTP API文档
• AEM Gem会话：OAuth