AEM Assets HTTP API中的内容片段支持 content-fragments-support-in-aem-assets-http-api
概述 overview
了解对Assets HTTP API中内容片段的支持,这是Adobe Experience Manager (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格式。
同时 AEM核心组件 提供可自定义的API,该API可为此目的提供所需的读取操作,并且可以自定义其JSON输出,因此实施它们确实需要AEM WCM (Web内容管理)专业知识。 这是因为它们必须在基于专用AEM模板的页面中托管。 并非每个SPA开发组织都可以直接访问此类知识。
这是可以使用资产REST API的时间。 它允许开发人员直接访问资产(例如图像和内容片段),而无需先将资产嵌入页面,然后以序列化JSON格式交付其内容。
Assets REST API还允许开发人员通过创建新资产、更新或删除现有资产、内容片段和文件夹来修改内容。
资产REST API:
前提条件 prerequisites
Assets REST API 在最新版本的 Adobe Experience Manager as a Cloud Service 的每个现成安装中提供。
重要概念 key-concepts
Assets REST API提供的 REST-style访问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
/api/assets
不 需要使用.model
选择器。/content/path/to/page
需要 使用.model
选择器。
HTTP 方法决定了要执行的操作:
- GET – 检索资产或文件夹的 JSON 表示形式
- POST — 创建资源或文件夹
- PUT – 更新资产或文件夹的属性
- DELETE – 删除资产或文件夹
支持的请求的确切格式在 API参考 文档。
事务性行为 transactional-behavior
所有请求都是原子的。
这表示随后(write
)请求无法组合为单个事务,该事务可能会作为单个实体成功或失败。
AEM (Assets) REST API与AEM组件 aem-assets-rest-api-versus-aem-components
(使用Sling模型的组件)
针对单页应用程序(SPA)或任何其他(使用内容)上下文中的使用情况进行了优化。
它还可以包含布局信息。
创建、读取、更新、删除。
附加操作,具体取决于实体类型。
可以直接访问。
使用 /api/assets
端点,映射到 /content/dam
(在存储库中)。
示例路径如下所示: /api/assets/wknd/en/adventures/cycling-tuscany.json
必须通过AEM页面上的AEM组件引用它。
使用 .model
选择器创建JSON表示形式。
示例路径如下所示:/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
可以使用多个选项。
建议使用OAuth;可以独立于标准设置进行配置。
写访问通常针对创作实例。
也可以将读取定向到发布实例。
安全性 security
如果在没有特定身份验证要求的环境中使用Assets REST API,则必须正确配置AEM CORS过滤器。
在具有特定身份验证要求的环境中,建议使用OAuth。
可用功能 available-features
内容片段是一种特定类型的资产,请参阅 使用内容片段.
有关通过API提供的功能的更多信息,请参阅:
- 此 Assets REST API
- 实体类型,其中说明了特定于每个受支持类型(与内容片段相关)的功能
分页 paging
Assets REST API支持通过URL参数进行分页(用于GET请求):
offset
— 要检索的第一个(子)实体的编号limit
— 返回的最大实体数
响应包含分页信息,作为 properties
部分。 此 srn:paging
属性包含(子)实体的总数( total
)、偏移和限制( offset
, limit
)。
示例:分页 example-paging
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
实体类型 entity-types
文件夹 folders
文件夹充当资源和其他文件夹的容器。 它们反映了AEM内容存储库的结构。
Assets REST API公开对文件夹属性的访问权限。 例如,其名称和标题。 资产将作为文件夹和子文件夹的子实体显示。
资源 assets
如果请求资产,则响应将返回其元数据;例如标题、名称以及各个资产架构定义的其他信息。
资产的二进制数据将作为类型的SIREN链接公开 content
.
资源可以具有多个演绎版。 它们通常作为子实体公开,但缩略图演绎版除外,该演绎版以类型的链接公开 thumbnail
( rel="thumbnail"
)。
内容片段 content-fragments
A 内容片段 是一种特殊类型的资产。 它们可用于访问结构化数据,如文本、数字、日期等。
由于与以下内容存在若干区别 标准 资产(例如图像或音频)时,会应用一些其他规则来处理它们。
呈现 representation
内容片段:
-
不要公开任何二进制数据。
-
包含在JSON输出中(在
properties
属性)。 -
它们也被认为是原子的。 也就是说,元素和变体作为片段属性的一部分显示,而不是作为链接或子实体显示。 这样可以高效地访问片段的负载。
内容模型和内容片段 content-models-and-content-fragments
目前,定义内容片段结构的模型不会通过HTTP API公开。 因此, 消费者 必须了解片段的模型(至少是最低限度) — 尽管可以从有效负载推断出大多数信息;由于数据类型等是定义的一部分。
要创建内容片段,必须提供模型的(内部存储库)路径。
关联的内容 associated-content
关联内容未公开。
使用 using
根据您使用的是AEM Author还是Publish环境,以及您的特定用例,使用方式会有所不同。
-
建议将创建绑定到创作实例(并且当前没有方法复制片段以使用此API发布)。
-
可以通过这两种方式交付,因为 AEM 仅以 JSON 格式提供请求的内容。
-
对于防火墙后的媒体库应用程序,AEM创作实例的存储和交付应已足够。
-
对于实时Web交付,建议使用AEM发布实例。
-
/api
.限制 limitations
有一些限制:
- 当前不支持内容片段模型:无法读取或创建它们。 为了能够创建或更新现有的内容片段,开发人员必须知道内容片段模型的正确路径。 目前,获取这些内容的概述的唯一方法是通过管理UI。
- 引用将被忽略. 当前不检查是否引用了现有的内容片段。 因此,例如,删除内容片段可能会导致包含对已删除内容片段的引用的页面出现问题。
- JSON数据类型 的REST API输出 JSON数据类型 是 基于字符串的输出.
状态代码和错误消息 status-codes-and-error-messages
在相关情况下可以看到以下状态代码:
-
200 (确定)
返回时间:
- 通过以下方式请求内容片段
GET
- 通过以下方式成功更新内容片段
PUT
- 通过以下方式请求内容片段
-
201 (已创建)
返回时间:
- 通过以下方式成功创建内容片段
POST
- 通过以下方式成功创建内容片段
-
404 (未找到)
返回时间:
- 请求的内容片段不存在
-
500 (内部服务器错误)
note note NOTE 返回此错误: - 当发生无法使用特定代码标识的错误时
- 当给定的有效负载无效时
下面列出了返回此错误状态以及生成的错误消息(等宽)时的常见情况:
-
父文件夹不存在(在通过创建内容片段时)
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
通过以下方式返回详细的错误消息:
code language-xml { "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-reference
有关详细的API参考,请参阅此处:
其他资源 additional-resources
有关更多信息,请参阅: