AEM Assets HTTP API 內容片段支援

概觀

瞭解Assets HTTP API支援內容片段，這是AEM Headless傳送功能的重要一環。

此 Assets REST API 可讓Adobe Experience Manager的開發人員透過CRUD作業（建立、讀取、更新、刪除），直接透過HTTP API存取內容(儲存在AEM中)。

此API可讓您藉由向JavaScript前端應用程式提供內容服務，將Adobe Experience Manager當作Headless CMS （內容管理系統）來運作。 或者任何其他可以執行 HTTP 要求並處理 JSON 回應的應用程式。

例如，單頁應用程式(SPA)，以框架為基礎或自訂，需要透過HTTP API提供的內容，通常為JSON格式。

當 AEM Core Components 提供非常完整、彈性且可自訂的API，可為此用途提供所需的讀取作業，且可自訂其JSON輸出，實作時確實需要AEM WCM （Web內容管理）專門技術，因為它們必須託管在基於專用AEM範本的頁面中。 並非每個SPA開發組織都能直接存取這些知識。

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

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

Assets REST API：

• 遵循 HATEOAS原則

• 實作 警鈴格式

先決條件

Assets REST API適用於最新版AEM的每次現成安裝。

重要概念

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

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

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

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

異動行為

所有要求都是原子的。

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

AEM (Assets) REST API與AEM元件

安全性

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

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

可用功能

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

如需透過API可用功能的詳細資訊，請參閱：

• 此 Assets REST 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 作者執行個體的儲存和傳遞操作應該足以滿足防火牆後的媒體庫應用程式的需求。

  • 如果是即時 Web 傳遞，則建議使用 AEM 發佈執行個體。

讀取/傳遞

使用方式：

GET /{cfParentPath}/{cfName}.json

例如：

http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json

回應是序列化的 JSON，其內容結構與內容片段中的一樣。參考是以參考 URL 的形式傳遞。

可能有兩種類型的讀取操作：

• 按路徑讀取特定內容片段，這將傳回內容片段的 JSON 表示。
• 按路徑讀取內容片段資料夾：這將傳回資料夾內所有內容片段的 JSON 表示。

建立

使用方式：

POST /{cfParentPath}/{cfName}

內文必須包含要建立的內容片段的 JSON 表示，包括應在內容片段元素上設定的任何初始內容。必須設定 cq:model 屬性，並且它必須指向有效的內容片段模型。未這麼做會導致錯誤。也必須加上標頭 Content-Type，其設定為 application/json。

更新

使用方式：

PUT /{cfParentPath}/{cfName}

內文必須包含給定內容片段要更新之內容的 JSON 表示。

這可以只是內容片段的標題或描述，或單一元素，或所有元素值和/或中繼資料。

刪除

使用方式：

DELETE /{cfParentPath}/{cfName}

限制

有幾項限制：

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

• Adobe Experience Manager Assets API - 內容片段

• Assets HTTP API

  • 可用功能

其他資源

如需進一步詳細資訊，請參閱：

• Assets HTTP API檔案
• AEM Gem工作階段： OAuth