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

概述

了解资产HTTP API中对内容片段的支持，HTTP API是AEM的一项重要无头交付功能。

注意

资产HTTP API包含：

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

资产HTTP API的当前实施基于REST架构样式。

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

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

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

虽然AEM核心组件提供了一个非常全面、灵活且可自定义的API，该API可为此目的提供所需的读取操作，并且其JSON输出可以自定义，但它们确实需要AEM WCM（Web内容管理）的专门技术来实施，因为它们必须在基于专用AEM模板的页面中托管。 并非每个SPA开发组织都能直接获取此类知识。

此时可以使用资产REST API。 它允许开发人员直接访问资产（例如，图像和内容片段），而无需先将资产嵌入到页面中，然后以序列化JSON格式交付其内容。

注意

无法从Assets REST API自定义JSON输出。

资产REST API还允许开发人员通过创建新资产、更新或删除现有资产、内容片段和文件夹来修改内容。

资产REST API:

前提条件

在最新AEM版本的每次现成安装中，都提供了Assets REST API。

重要概念

资产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 — 删除资产或文件夹
注意

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

支持的请求的确切格式在API引用文档中定义。

事务性行为

所有请求都是原子的。

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

AEM(Assets)REST API与AEM组件

方面 资产REST API
 AEM组件
（使用Sling模型的组件）
支持的用例 一般用途。

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

还可以包含布局信息。
支持的操作

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

根据实体类型使用其他操作。

 只读.
访问

可以直接访问。

使用映射到/content/dam的/api/assets 端点（在存储库中）。

示例路径如下所示： /api/assets/wknd/en/adventures/cycling-tuscany.json

需要在AEM页面上通过AEM组件引用。

使用.model选择器创建JSON表示形式。

示例路径如下所示：
/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
安全

可以使用多个选项。

OAuth是提出的；可以与标准设置分开配置。

 使用AEM标准设置。
建筑备注

写访问通常将寻址创作实例。

也可以将读取定向到发布实例。

 由于此方法为只读方法，因此通常将用于发布实例。
输出 基于JSON的SIREN输出：冗长，但功能强大。 允许在内容中导航。 基于JSON的专有输出；可通过Sling模型进行配置。 导览内容结构很难实现（但不一定不可能）。

安全

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

注意

有关更多信息，请参阅：

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

可用功能

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

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

分页

GETREST API支持通过URL参数进行分页（对于资产请求）：

  • 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类型的SIREN链接公开。

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

内容片段

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

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

表示

内容片段：

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

  • 完全包含在JSON输出中（在properties属性内）。

  • 也被视为原子，即元素和变量作为片段属性的一部分公开，而作为链接或子实体公开。 这允许有效访问片段的有效负载。

内容模型和内容片段

当前，定义内容片段结构的模型不会通过HTTP API公开。 因此，使用者​需要了解片段的模型（至少是一个最小值） — 尽管大多数信息都可以从负载中推断出来；数据类型等。 是定义的一部分。

要创建新的内容片段，必须提供模型的（内部存储库）路径。

关联的内容

关联的内容当前未公开。

使用

用法可能因您使用的是AEM创作环境还是发布环境以及特定用例而异。

  • 强烈建议将创建绑定到创作实例(，并且当前没有方法使用此API复制片段以发布。

  • 可以同时从两者进行交付，因为AEM仅以JSON格式提供请求的内容。

    • 从AEM创作实例进行存储和交付应足以在防火墙后部署媒体库应用程序。

    • 对于实时Web交付，建议使用AEM发布实例。

注意

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

注意

有关更多详细信息，请参阅API引用。 尤其是Adobe Experience Manager Assets API — 内容片段。

读取/投放

用法包括：

GET /{cfParentPath}/{cfName}.json

例如：

http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json

响应将以内容片段中的结构化进行序列化JSON。 引用作为引用URL提供。

可以执行两种类型的读取操作：

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

创建

用法包括：

POST /{cfParentPath}/{cfName}

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

更新

使用方式为

PUT /{cfParentPath}/{cfName}

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

这可以只是内容片段、单个元素或所有元素值和/或元数据的标题或描述。

删除

用法包括：

DELETE /{cfParentPath}/{cfName}

限制

存在以下几个限制：

  • 当前不支持内容片段模型:无法读取或创建它们。为了能够创建新内容片段或更新现有内容片段，开发人员必须知道内容片段模型的正确路径。 目前，获取这些内容概述的唯一方法是通过管理UI。
  • 将忽略引用。当前，没有检查是否引用了现有内容片段。 因此，例如，删除内容片段可能会导致页面上出现包含对已删除内容片段的引用的问题。
  • JSON数据 类型JSON数据类型的REST API输出当前 基于字 符串 的输出。

状态代码和错误消息

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

  • 200 (OK)在以下情况下返回：

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

  • 201 （已创建）在以下情况下返回：

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

  • 404 （未找到）在以下情况下返回：

    • 请求的内容片段不存在

  • 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参考，请参阅此处：

其他资源

有关更多信息，请参阅：

在此页面上