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

概述

注意

资产HTTP API包含:

  • 资产REST API
  • 包括对内容片段的支持

AEM Assets HTTP API的当前实现是REST。

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:

前提条件

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

重要概念

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

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

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

请求体和/或URL参数可用于配置其中的一些操作;例如,定义应由​POST​请求创建文件夹或资产。

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

事务行为

所有请求都是原子的。

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

AEM(Assets)REST API与AEM组件

Aspect 资产REST API
AEM Component
(使用Sling Models的组件)
支持的用例 一般用途。

已针对单页应用程序(SPA)或任何其他(内容消耗)上下文中的使用情况进行优化。

还可以包含布局信息。

支持的操作

创建、读取、更新、删除。

根据实体类型,包含其他操作。

只读.
访问

可以直接访问。

使用映射到/content/dam(在存储库中)的/api/assets 终结点。

例如,访问: /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 Model进行配置。 导航内容结构很难实现(但不一定不可能)。

安全

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

注意

有关更多信息,请参阅:

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

可用功能

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

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

分页

资产REST API支持通过URL参数进行分页(对于GET请求):

  • offset — 要检索的第一个(子)实体的编号
  • limit — 返回的最大实体数

响应将包含分页信息,作为SIREN输出的properties部分的一部分。 此srn:paging属性包含请求中指定的(子)实体(total)总数、偏移量和限制(offsetlimit)。

注意

分页通常应用于容器实体(即,与请求实体的子实体相关的文件夹或具有演绎版的资产)。

示例:分页

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发布实例。
注意

AEM云实例上的调度程序配置可能会阻止对/api的访问。

注意

有关详细信息,请参阅API参考。 特别是Adobe Experience Manager Assets API - Content Fragments

读/投放

使用方式:

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参考,请参阅此处:

其他资源

有关更多信息,请参阅:

On this page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now