AEM Assets HTTP API 內容片段支援

概覽

注意

Assets HTTP API包含:

  • 資產REST API
  • 包括支援內容片段

資產HTTP API的目前實作是以REST架構樣式為基礎。

Assets REST API可讓Adobe Experience Manager做為雲端服務的開發人員透過HTTP API直接存取內容(儲存在AEM中),透過CRUD作業(建立、讀取、更新、刪除)。

此API可讓您將Adobe Experience Manager當成雲端服務,以無頭CMS(內容管理系統)的形式運作,為JavaScript前端應用程式提供內容服務。 或是任何其他可執行HTTP要求和處理JSON回應的應用程式。

例如,單頁應用程式(SPA)、架構或自訂需要透過HTTP API提供的內容,通常是JSON格式。

雖然AEM核心元件提供非常完整、有彈性且可自訂的API,可針對此用途提供必要的讀取作業,而且可自訂其JSON輸出,但是它們確實需要AEM WCM(Web Content Management)專業知識,才能在以專用AEM範本為基礎的頁面中代管實作。 並非每個SPA開發組織都能直接獲得此類知識。

此時即可使用資產REST API。 它可讓開發人員直接存取資產(例如影像和內容片段),而不需先將資產內嵌在頁面中,然後以序號化JSON格式傳送其內容。

注意

無法從Assets REST API自訂JSON輸出。

Assets REST API也允許開發人員建立新資產、內容片段和資料夾,以修改內容。

資產REST API:

必備條件

資產REST API可在最新Adobe Experience Manager的每次即裝即用安裝中,以雲端服務版本提供。

重要概念

Assets 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 —— 更新資產或資料夾的屬性
  • 刪除 -刪除資產或資料夾
注意

請求正文和/或URL參數可用於配置其中的一些操作;例如,定義資料夾或資產應由​POST​請求建立。

API參考檔案中已定義支援請求的確切格式。

事務行為

所有請求都是原子的。

這表示後續(write)請求無法合併為單一實體可能成功或失敗的單一交易。

AEM(Assets)REST API與AEM元件

外觀 資產REST API
AEM Component
(使用Sling Models的元件)
支援的使用案例 一般用途。

已針對單頁應用程式(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 Models進行設定。 導覽內容結構很難實作(但不一定不可能)。

安全性

如果Assets REST API是在沒有特定驗證要求的環境中使用,AEM的CORS篩選器必須正確設定。

注意

在具有特定驗證需求的環境中,建議使用OAuth。

可用功能

「內容片段」是特定資產類型,請參閱使用內容片段

如需透過API提供之功能的詳細資訊,請參閱:

尋呼

資產REST API支援透過URL參數進行分頁(針對GET請求):

  • offset -要檢索的第一個(子)實體的編號
  • limit -傳回的實體數上限

響應將包含作為SIREN輸出properties部分的分頁資訊。 此srn:paging屬性包含請求中指定的(子)實體(total)總數、偏移和限制(offsetlimit)。

注意

分頁通常套用至容器實體(即資料夾或具有轉譯的資產),因為它與所請求實體的子系相關。

範例:尋呼

GET /api/assets.json?offset=2&limit=3

...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

實體類型

資料夾

資料夾可當成資產和其他資料夾的容器。 它們反映AEM內容存放庫的結構。

Assets REST API會公開資料夾屬性的存取權;例如其名稱、標題等。 資產會以資料夾的子實體和子資料夾的形式公開。

注意

根據子資產和資料夾的資產類型,子實體清單可能已包含定義各子實體的完整屬性集。 或者,在該子實體清單中,僅可針對實體公開一組縮小的屬性。

資產

如果要求資產,回應會傳回其中繼資料;例如標題、名稱及由個別資產架構定義的其他資訊。

資產的二進位資料以content類型的SIREN連結的形式公開。

資產可以有多個轉譯。 這些項目通常以子實體形式公開,但有一個例外是縮略圖格式副本,它以類型thumbnail(rel="thumbnail")的連結形式公開。

內容片段

內容片段是特殊類型的資產。 它們可用於存取結構化資料,例如文字、數字、日期等。

由於​standard​資產(例如影像或音訊)有數項差異,因此處理資產時會套用一些其他規則。

表示

內容片段:

  • 請勿公開任何二進位資料。

  • 完全包含在JSON輸出中(位於properties屬性中)。

  • 也被視為原子,即元素和變化作為片段屬性的一部分而暴露,而不是作為連結或子實體。 這允許有效訪問片段的負載。

內容模型和內容片段

目前,定義內容片段結構的模型不會透過HTTP API公開。 因此,consumer​需要瞭解片段的模型(至少是最小值)-儘管大部分資訊可以從負載中推斷出來;資料類型等。 是定義的一部分。

要建立新內容片段,必須提供模型的(內部儲存庫)路徑。

相關聯的內容

相關內容目前未公開。

使用

使用情形可能會因您使用AEM作者或發佈環境以及您的特定使用案例而異。

  • 強烈建議建立作業系結至作者例項(,目前無法使用此API復製片段以發佈)。

  • 兩者皆可傳送,因為AEM僅以JSON格式提供要求的內容。

    • 從AEM作者實例儲存和傳送的內容,應該足以滿足防火牆後、媒體程式庫應用程式的需求。

    • 若是即時網路傳送,建議使用AEM發佈例項。

注意

AEM雲端例項上的Dispatcher設定可能會封鎖對/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屬性,且必須指向有效的內容片段模型。 若無法這麼做,將會導致錯誤。 此外,還需要添加將設定為application/json的標題Content-Type

更新

使用方式是透過

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參考,請參閱此處:

其他資源

如需詳細資訊,請參閱:

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free