文档AEM 6.5用户指南

Assets HTTP API assets-http-api

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 开发人员
版本
文章链接
AEM as a Cloud Service
单击此处
AEM 6.5
本文

概述 overview

Assets HTTP API允许对数字资源执行创建 — 读取 — 更新 — 删除(CRUD)操作，包括对元数据、演绎版和评论的操作，以及使用Experience Manager内容片段的结构化内容。 它在/api/assets中公开，并作为REST API实现。 它包括对内容片段🔗的支持。

要访问API，请执行以下操作：

  1. 在https://[hostname]:[port]/api.json处打开API服务文档。
  2. 关注指向https://[hostname]:[server]/api/assets.json的Assets服务链接。

API响应是适用于某些MIME类型的JSON文件，是适用于所有MIME类型的响应代码。 JSON响应是可选的，可能无法用于（例如）PDF文件。 依靠响应代码进行进一步分析或执行操作。

在结束时间后，无法通过Assets Web界面和HTTP API使用资产及其演绎版。 如果开启时间是未来的时间，或者结束时间是过去的时间，则API会返回404错误消息。

CAUTION
HTTP API更新jcr命名空间中的元数据属性。 但是，Experience Manager用户界面会更新dc命名空间中的元数据属性。

内容片段 content-fragments

内容片段是一种特殊类型的资产。 它可用于访问结构化数据，如文本、数字、日期等。 由于standard资产（如图像或文档）存在若干差异，因此处理内容片段时适用一些其他规则。

有关详细信息，请参阅Experience Manager Assets HTTP API中的内容片段支持。

数据模型 data-model

Assets HTTP API公开两个主要元素：文件夹和资源（用于标准资源）。

此外，它会为描述内容片段中结构化内容的自定义数据模型显示更详细的元素。 有关详细信息，请参阅内容片段数据模型。

文件夹 folders

文件夹类似于传统文件系统中的目录。 它们是其他文件夹或断言的容器。 文件夹具有以下组件：

实体：文件夹的实体是其子元素，可以是文件夹和资源。

属性：

  • name是文件夹的名称。 这与URL路径中没有扩展的最后一个区段相同。
  • title是文件夹的可选标题，可以显示它而不是其名称。
NOTE
文件夹或资产的某些属性映射到不同的前缀。 jcr:title、jcr:description和jcr:language的jcr前缀已替换为dc前缀。 因此，在返回的JSON中，dc:title和dc:description分别包含jcr:title和jcr:description的值。

链接 ​文件夹显示三个链接：

  • self：链接到自身。
  • parent：链接到父文件夹。
  • thumbnail：（可选）链接到文件夹缩略图图像。

资源 assets

在Experience Manager中，资源包含以下元素：

  • 资源的属性和元数据。
  • 多个演绎版，例如原始演绎版（最初上传的资源）、缩略图以及各种其他演绎版。 其他演绎版可以是大小不同、视频编码不同的图像，或者从PDF或Adobe InDesign文件中提取的页面。
  • 可选注释。

有关内容片段中元素的信息，请参阅Experience Manager Assets HTTP API中的内容片段支持。

在Experience Manager中，文件夹具有以下组件：

  • 实体：资产的子项是其演绎版。
  • 属性。
  • 链接。

Assets HTTP API包含以下功能：

NOTE
为了便于阅读，以下示例省略了完整的cURL表示法。 事实上，表示法与Resty相关联，后者是cURL的脚本包装器。

前提条件

  • 访问https://[aem_server]:[port]/system/console/configMgr。
  • 导航到​ AdobeGranite CSRF筛选器。
  • 确保属性​ 筛选器方法 ​包括： POST、PUT、DELETE。

检索文件夹列表 retrieve-a-folder-listing

检索现有文件夹及其子实体（子文件夹或资产）的Siren表示形式。

请求： GET /api/assets/myFolder.json

响应代码：响应代码为：

  • 200 — 确定 — 成功。
  • 404 - NOT FOUND — 文件夹不存在或无法访问。
  • 500 — 内部服务器错误 — 如果出现其他错误。

响应：返回的实体的类是资产或文件夹。 包含的实体的属性是每个实体的完整属性集的子集。 要获取实体的完整表示形式，客户端应检索链接指向的URL的内容，该URL具有self的rel。

创建文件夹 create-a-folder

在给定路径创建新sling： OrderedFolder。 如果提供了*而不是节点名称，则servlet将使用该参数名称作为节点名称。 已接受，因为请求数据是新文件夹的Siren表示形式或一组名称 — 值对，编码为application/www-form-urlencoded或multipart/form- data，可用于直接从HTML表单创建文件夹。 此外，可以将文件夹的属性指定为URL查询参数。

如果提供的路径的父节点不存在，则API调用会失败，并返回500响应代码。 如果文件夹已存在，调用将返回响应代码409。

参数： name是文件夹名称。

请求

  • POST /api/assets/myFolder -H"Content-Type: application/json" -d '{"class":"assetFolder","properties":{"jcr:title":"My Folder"}}'
  • POST /api/assets/* -F"name=myfolder" -F"jcr:title=My Folder"

响应代码：响应代码为：

  • 201 — 已创建 — 成功创建时。
  • 409 — 冲突 — 如果文件夹已存在。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

创建资产 create-an-asset

将提供的文件放在提供的路径中，以在DAM存储库中创建资产。 如果提供*而不是节点名称，则servlet使用参数名称或文件名作为节点名称。

参数：参数为资源名称的name和文件引用的file。

请求

  • POST /api/assets/myFolder/myAsset.png -H"Content-Type: image/png" --data-binary "@myPicture.png"
  • POST /api/assets/myFolder/* -F"name=myAsset.png" -F"file=@myPicture.png"

响应代码：响应代码为：

  • 201 - CREATED — 如果已成功创建资产。
  • 409 — 冲突 — 如果资产已存在。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

更新资产二进制文件 update-asset-binary

更新资源的二进制文件（名为原始的演绎版）。 如果进行了配置，更新会触发默认资产处理工作流执行。

请求： PUT /api/assets/myfolder/myAsset.png -H"Content-Type: image/png" --data-binary @myPicture.png

响应代码：响应代码为：

  • 200 — 确定 — 如果已成功更新资产。
  • 404 - NOT FOUND — 如果在提供的URI中找不到或无法访问资产。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

更新资源元数据 update-asset-metadata

更新资源元数据属性。 如果更新dc:命名空间中的任何属性，则API会更新jcr命名空间中的相同属性。 该API不会同步两个命名空间下的属性。

请求： PUT /api/assets/myfolder/myAsset.png -H"Content-Type: application/json" -d '{"class":"asset", "properties":{"jcr:title":"My Asset"}}'

响应代码：响应代码为：

  • 200 — 确定 — 如果已成功更新资产。
  • 404 - NOT FOUND — 如果在提供的URI中找不到或无法访问资产。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

dc和jcr命名空间之间的同步元数据更新 sync-metadata-between-namespaces

API方法更新jcr命名空间中的元数据属性。 使用用户界面进行的更新会更改dc命名空间中的元数据属性。 若要同步dc和jcr命名空间之间的元数据值，您可以创建工作流并配置Experience Manager以在编辑资源时执行工作流。 使用ECMA脚本同步所需的元数据属性。 以下示例脚本在dc:title和jcr:title之间同步标题字符串。

var workflowData = workItem.getWorkflowData();
if (workflowData.getPayloadType() == "JCR_PATH")
{
 var path = workflowData.getPayload().toString();
 var node = workflowSession.getSession().getItem(path);
 var metadataNode = node.getNode("jcr:content/metadata");
 var jcrcontentNode = node.getNode("jcr:content");
if (jcrcontentNode.hasProperty("jcr:title"))
{
 var jcrTitle = jcrcontentNode.getProperty("jcr:title");
 metadataNode.setProperty("dc:title", jcrTitle.toString());
 metadataNode.save();
}
}

创建资源演绎版 create-an-asset-rendition

为资源创建资源演绎版。 如果未提供请求参数名称，则使用文件名作为演绎版名称。

参数：格式副本的名称为name，文件引用为file。

请求

  • POST /api/assets/myfolder/myasset.png/renditions/web-rendition -H"Content-Type: image/png" --data-binary "@myRendition.png"
  • POST /api/assets/myfolder/myasset.png/renditions/* -F"name=web-rendition" -F"file=@myRendition.png"

响应代码：响应代码为：

  • 201 - CREATED — 如果已成功创建呈现版本。
  • 404 - NOT FOUND — 如果在提供的URI中找不到或无法访问资产。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

更新资源演绎版 update-an-asset-rendition

更新分别使用新的二进制数据替换资产演绎版。

请求： PUT /api/assets/myfolder/myasset.png/renditions/myRendition.png -H"Content-Type: image/png" --data-binary @myRendition.png

响应代码：响应代码为：

  • 200 - OK — 如果已成功更新演绎版。
  • 404 - NOT FOUND — 如果在提供的URI中找不到或无法访问资产。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

在资产上添加评论 create-an-asset-comment

创建新的资产注释。

参数：评论的消息正文的参数为message，JSON格式的注释数据的参数为annotationData。

请求： POST /api/assets/myfolder/myasset.png/comments/* -F"message=Hello World." -F"annotationData={}"

响应代码：响应代码为：

  • 201 - CREATED — 如果评论已成功创建。
  • 404 - NOT FOUND — 如果在提供的URI中找不到或无法访问资产。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

复制文件夹或资源 copy-a-folder-or-asset

将提供的路径中可用的文件夹或资产复制到新目标。

请求标头：参数为：

  • X-Destination - API解决方案作用域中要将资源复制到的新目标URI。
  • X-Depth - infinity或0。 使用0仅复制资源及其属性，而不复制其子项。
  • X-Overwrite — 使用F防止覆盖现有目标上的资产。

请求： COPY /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-copy"

响应代码：响应代码为：

  • 201 - CREATED — 文件夹/资产是否已复制到不存在的目标。
  • 204 — 无内容 — 如果将文件夹/资产复制到现有目标。
  • 412 - PRECONDITION失败 — 如果缺少请求标头。
  • 500 — 内部服务器错误 — 如果出现其他错误。

移动文件夹或资源 move-a-folder-or-asset

将给定路径下的文件夹或资源移动到新目标。

请求标头：参数为：

  • X-Destination - API解决方案作用域中要将资源复制到的新目标URI。
  • X-Depth - infinity或0。 使用0仅复制资源及其属性，而不复制其子项。
  • X-Overwrite — 使用T强制删除现有资源，或使用F阻止覆盖现有资源。

请求： MOVE /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-moved"

请勿在URL中使用/content/dam。 移动资源和覆盖现有资源的示例命令为：

curl -u admin:admin -X MOVE https://[aem_server]:[port]/api/assets/source/file.png -H "X-Destination: https://[aem_server]:[port]/api/assets/destination/file.png" -H "X-Overwrite: T"

响应代码：响应代码为：

  • 201 - CREATED — 文件夹/资产是否已复制到不存在的目标。
  • 204 — 无内容 — 如果将文件夹/资产复制到现有目标。
  • 412 - PRECONDITION失败 — 如果缺少请求标头。
  • 500 — 内部服务器错误 — 如果出现其他错误。

删除文件夹、资源或演绎版 delete-a-folder-asset-or-rendition

在提供的路径中删除资源(-tree)。

请求

  • DELETE /api/assets/myFolder
  • DELETE /api/assets/myFolder/myAsset.png
  • DELETE /api/assets/myFolder/myAsset.png/renditions/original

响应代码：响应代码为：

  • 200 - OK — 已成功删除文件夹。
  • 412 - PRECONDITION FAILED — 如果找不到或无法访问根集合。
  • 500 — 内部服务器错误 — 如果出现其他错误。

提示和限制 tips-best-practices-limitations

  • HTTP API更新jcr命名空间中的元数据属性。 但是，Experience Manager用户界面会更新dc命名空间中的元数据属性。

  • Assets HTTP API不返回完整的元数据。 命名空间是硬编码的，并且只返回这些命名空间。 有关完整的元数据，请参阅资源路径/jcr_content/metadata.json。

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2