Assets HTTP API assets-http-api

版本
文章連結
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網頁介面及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:titlejcr:descriptionjcr:languagejcr首碼已取代為dc首碼。 因此,在傳回的JSON中,dc:titledc:description分別包含jcr:titlejcr:description的值。

連結 ​資料夾公開三個連結:

  • self:連結到本身。
  • parent:連結至父資料夾。
  • thumbnail: (選用)連結至資料夾縮圖影像。

Assets 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篩選器
  • 確定屬性​ 篩選方法 ​包含: POSTPUTDELETE

擷取資料夾清單 retrieve-a-folder-listing

擷取現有資料夾及其子系圖元(子資料夾或資產)的Siren表示。

要求GET /api/assets/myFolder.json

回應代碼:回應代碼為:

  • 200 — 確定 — 成功。
  • 404 - NOT FOUND — 資料夾不存在或無法存取。
  • 500 — 內部伺服器錯誤 — 如果發生其他錯誤。

回應:傳回的實體類別是資產或資料夾。 包含之圖元的屬性是每個圖元之完整屬性集的子集。 若要取得實體的完整表示法,使用者端應擷取連結所指向的URL內容,該URL具有selfrel

建立資料夾 create-a-folder

在指定路徑建立新的slingOrderedFolder。 如果提供*而非節點名稱,則servlet會使用引數名稱作為節點名稱。 接受的要求資料是新資料夾的Siren表示或一組名稱 — 值組,編碼為application/www-form-urlencodedmultipart/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 — 已建立 — 資產是否已成功建立。
  • 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 — 內部伺服器錯誤 — 如果發生其他錯誤。

dcjcr名稱空間之間的同步中繼資料更新 sync-metadata-between-namespaces

API方法會更新jcr名稱空間中的中繼資料屬性。 使用使用者介面進行的更新會變更dc名稱空間中的中繼資料屬性。 若要同步dcjcr名稱空間之間的中繼資料值,您可以建立工作流程並設定Experience Manager,以在資產編輯時執行工作流程。 使用ECMA指令碼來同步所需的中繼資料屬性。 下列範例指令碼會在dc:titlejcr: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 — 確定 — 如果已成功更新轉譯。
  • 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 - infinity0。 使用0只會複製資源及其屬性,不會複製其子系。
  • X-Overwrite — 使用F防止覆寫現有目的地的資產。

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

回應代碼:回應代碼為:

  • 201 - CREATED — 若資料夾/資產已複製到不存在的目的地。
  • 204 — 無內容 — 若資料夾/資產已複製到現有目的地。
  • 412 — 先決條件失敗 — 如果缺少請求標頭。
  • 500 — 內部伺服器錯誤 — 如果發生其他錯誤。

行動資料夾或資產 move-a-folder-or-asset

將指定路徑的資料夾或資產移至新目的地。

要求標頭:引數為:

  • X-Destination - API解決方案範圍內的新目的地URI,可將資源複製到其中。
  • X-Depth - infinity0。 使用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 — 先決條件失敗 — 如果缺少請求標頭。
  • 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 — 確定 — 如果資料夾已成功刪除。
  • 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