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

概述

了解Assets HTTP API中对内容片段的支持，这是AEM Headless投放功能的重要部分。

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

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

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

While AEM核心组件 提供非常全面、灵活且可自定义的API，该API可为此目的提供所需的读取操作，并且其JSON输出可自定义，因此它们确实需要AEM WCM（Web内容管理）专门知识才能实施，因为它们必须托管在基于专用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提供 REST — 样式访问AEM实例中存储的资源。

它使用 /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 — 返回的最大实体数

响应将包含寻呼信息，作为 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

如果请求资产，响应将返回其元数据；例如标题、名称以及各个资产架构定义的其他信息。

资产的二进制数据将作为类型的SIREN链接公开 content.

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

内容片段

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

由于与以下内容存在若干差异： 标准 资产（如图像或音频）时，会应用一些其他规则来处理它们。

呈现

内容片段：

• 不要公开任何二进制数据。

• 完全包含在JSON输出中(在 properties 属性)。

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

内容模型和内容片段

目前，定义内容片段结构的模型不会通过HTTP API公开。 因此， 消费者 需要了解片段的模型（至少是最低限度） — 尽管大多数信息可以从有效负载中推断；数据类型等。 是定义的一部分。

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

关联的内容

关联内容当前未公开。

使用

根据您使用的是 AEM 创作环境还是发布环境以及您的具体用例，使用情况可能会有所不同。

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

• 可以通过这两种方式交付，因为 AEM 仅以 JSON 格式提供请求的内容。

  • 来自 AEM 创作实例的存储和交付应足以满足防火墙背后的媒体库应用程序的需求。

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

限制

有一些限制：

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

状态代码和错误消息

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

• 200 （确定）

  返回时间：

  • 通过以下方式请求内容片段 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参考：

• Adobe Experience Manager Assets API – 内容片段

• Assets HTTP API

  • 可用功能

其他资源

有关更多信息，请参阅：

• Assets HTTP API文档
• AEM Gem会话： OAuth

Business.Adobe.com 资源