AEM Assets HTTP API 內容片段支援

概觀

版本 文章連結
AEM 6.5 按一下這裡
AEM as a Cloud Service 本文章

瞭解資產HTTP API支援內容片段，這是Adobe Experience Manager (AEM) Headless傳送功能的重要一環。

注意

此 Assets HTTP API 包括：

  • Assets REST API
  • 包含支援內容片段

Assets HTTP API的目前實作是根據 REST 架構樣式。

此 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 Core Components 提供可自訂的API，該API可提供此用途的必要讀取作業，且其JSON輸出可自訂，這些實作需要AEM WCM （Web內容管理）專門技術。 這是因為它們必須託管在基於專用AEM範本的頁面中。 並非每個SPA開發組織都能直接存取這些知識。

此時可使用Assets REST API。 它可讓開發人員直接存取資產（例如影像和內容片段），而不需要先將資產內嵌在頁面中，並以序列化JSON格式傳送其內容。

注意

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

Assets REST API也可讓開發人員透過建立新、更新或刪除現有資產、內容片段和資料夾來修改內容。

Assets REST API：

先決條件

Adobe Experience Manager as a Cloud Service 最新版本的每個開箱即用安裝中都有提供 Assets REST API。

重要概念

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

注意

存取：

  • /api/assets不需要​使用 .model 選擇器。
  • /content/path/to/page 需要​使用 .model 選擇器。

HTTP 方法決定要執行的操作：

  • GET - 檢索資產或資料夾的 JSON 表示
  • POST — 建立資產或資料夾
  • PUT - 更新資產或資料夾的屬性
  • DELETE - 刪除資產或資料夾
注意

要求內文和/或 URL 參數可用於設定其中一些操作；例如，定義資料夾或資產應由 POST 要求建立。

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

異動行為

所有要求都是原子的。

這表示後續的(write)要求無法結合成單一交易，而此交易可能會以單一實體成功或失敗。

AEM (Assets) REST API與AEM元件

外觀 Assets REST API
 AEM元件
（使用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；可與標準設定分開設定。

 使用AEM標準設定。
架構註解

寫入存取權通常可處理作者例項。

讀取可能會被導向到發佈執行個體。

 由於此方法為唯讀，因此通常會用於Publish例項。
輸出 JSON型SIREN輸出：冗長但功能強大。 它允許在內容內導覽。 JSON型專有輸出；可透過Sling模型設定。 導覽內容結構難以實作（但並非一定不可能）。

安全性

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

注意

如需詳細資訊，請參閱：

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

可用功能

內容片段是特定型別的資產，請參閱 使用內容片段.

如需透過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編寫執行個體的儲存和傳送應已足夠。

    • 對於即時網頁傳送，建議使用AEM Publish執行個體。

注意

AEM雲端例項上的Dispatcher設定可能會封鎖對的存取 /api.

注意

如需詳細資訊，請參閱 API參考. 特別是 Adobe Experience Manager Assets API - 內容片段。

限制

有幾項限制：

  • 目前不支援內容片段模型：它們無法讀取或建立。 為了能夠建立新的或更新現有的內容片段，開發人員必須知道內容片段模型的正確路徑。 目前，取得這些內容的概觀的唯一方法就是透過管理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參考資料，請參閱此處：

其他資源

如需詳細資訊，請參閱：

本頁內容