文件AEM 6.5使用手冊

AEM Assets HTTP API中的內容片段支援 content-fragments-support-in-aem-assets-http-api

Last update: Sun Jul 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 開發人員
版本
文章連結
AEM as a Cloud Service
按一下這裡
AEM 6.5
本文章

概觀 overview

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

NOTE
Assets HTTP API包含：
  • Assets REST API
  • 包含支援內容片段
Assets HTTP API目前的實作是以REST架構樣式為基礎。

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

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

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

雖然AEM核心元件提供非常完整、彈性且可自訂的API，可提供此用途的必要讀取作業以及可自訂的JSON輸出，但是這些元件確實需要AEM WCM （網頁內容管理）專門知識才能實作，因為它們必須託管在基於專用AEM範本的頁面中。 並非每個SPA開發組織都能直接存取這些知識。

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

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

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

Assets REST API：

先決條件 prerequisites

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

重要概念 key-concepts

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

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

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

  • GET - 檢索資產或資料夾的 JSON 表示
  • POST - 建立新資產或資料夾
  • PUT - 更新資產或資料夾的屬性
  • DELETE - 刪除資產或資料夾
NOTE
要求內文和/或 URL 參數可用於設定其中一些操作；例如，定義資料夾或資產應由 POST 要求建立。

在API參考檔案中定義了支援要求的確切格式。

異動行為 transactional-behavior

所有要求都是原子的。

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

AEM (Assets) REST API與AEM元件 aem-assets-rest-api-versus-aem-components

外觀
Assets REST API
AEM元件
（使用Sling模型的元件）
支援的使用案例
一般用途。

針對單頁應用程式(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模型設定。 導覽內容結構難以實作（但並非一定不可能）。

安全性 security

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

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

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

可用功能 available-features

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

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

分頁 paging

Assets REST API支援透過URL引數分頁(針對GET請求)：

  • offset — 要擷取的第一個（子項）實體數目
  • limit — 傳回的實體數上限

回應將包含分頁資訊，作為SIREN輸出之properties區段的一部分。 此srn:paging屬性包含要求中所指定的（子）實體總數( total)、位移和限制( offset， limit)。

NOTE
分頁通常會套用至容器實體（即資料夾或具有轉譯的資產），因為它與請求實體的子系相關。

範例：分頁 example-paging

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

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

實體型別 entity-types

資料夾 folders

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

Assets REST API會顯示資料夾屬性的存取權，例如其名稱、標題等。 Assets會公開為資料夾和子資料夾的子實體。

NOTE
根據子資產和資料夾的資產型別，子實體清單可能已經包含定義個別子實體的完整屬性集。 或者，在此子圖元清單中，只能為圖元顯示縮減的屬性集。

Assets assets

如果資產已要求，回應會傳回其中繼資料，例如標題、名稱和個別資產結構描述所定義的其他資訊。

資產的二進位資料會公開為型別content的SIREN連結。

Assets可以有多個轉譯。 這些通常會顯示為子實體，其中一個例外是縮圖轉譯，這會公開為型別thumbnail ( rel="thumbnail")的連結。

內容片段 content-fragments

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

由於​ 標準 ​資產（例如影像或音訊）有幾項差異，因此處理這些資產需套用其他規則。

表示 representation

內容片段：

  • 不要公開任何二進位資料。

  • 完全包含在JSON輸出中（在properties屬性內）。

  • 也視為原子元素，也就是說，元素和變數會作為片段屬性的一部分公開，而不是作為連結或子實體公開。 這樣可讓您有效率地存取片段的裝載。

內容模型和內容片段 content-models-and-content-fragments

目前，定義內容片段結構的模型不會透過HTTP API公開。 因此，消費者 ​需要知道片段的模型（至少是最低限度） — 雖然大多數資訊可以從承載推斷；以資料型別推斷，以此類推。 是定義的一部分。

若要建立內容片段，必須提供模型的（內部存放庫）路徑。

相關聯的內容 associated-content

關聯內容目前未公開。

使用 using

根據您使用的是 AEM 作者環境還是發佈環境，以及您的特定使用案例，使用情況可能會有所不同。

  • 強烈建議將建立繫結至作者執行個體()，目前沒有方法可使用此API將片段復寫至發佈)。

  • 都可以從兩者傳遞，因為 AEM 僅以 JSON 格式提供要求的內容。

    • 來自 AEM 作者執行個體的儲存和傳遞操作應該足以滿足防火牆後的媒體庫應用程式的需求。

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

CAUTION
AEM執行個體上的Dispatcher設定可能會封鎖對/api的存取權。
NOTE
如需詳細資訊，請參閱API參考。 特別是 Adobe Experience Manager Assets API - 內容片段。

讀取/傳遞 read-delivery

使用方式：

GET /{cfParentPath}/{cfName}.json

例如：

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

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

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

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

建立 create

使用方式：

POST /{cfParentPath}/{cfName}

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

更新 update

使用方式：

PUT /{cfParentPath}/{cfName}

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

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

刪除 delete

使用方式：

DELETE /{cfParentPath}/{cfName}

限制 limitations

有幾項限制：

  • 目前不支援內容片段模型：無法讀取或建立這些模型。 為了能夠建立內容片段或更新現有片段，開發人員必須知道內容片段模式的正確路徑。 目前，取得這些內容的概觀的唯一方法就是透過管理UI。
  • 已忽略​ 個參考。 目前沒有檢查是否參考了現有的內容片段。 因此，例如，刪除內容片段可能會導致包含已刪除內容片段參考的頁面發生問題。
  • JSON資料型別 JSON資料型別 ​的REST API輸出目前是​ 字串型輸出。

狀態代碼和錯誤訊息 status-codes-and-error-messages

在相關環境中可以看到下列狀態代碼：

  • 200 （確定）
    傳回時間：

    • 透過GET要求內容片段
    • 透過PUT成功更新內容片段

  • 201 （已建立）
    傳回時間：

    • 透過POST成功建立內容片段

  • 404 （找不到）
    傳回時間：

    • 要求的內容片段不存在

  • 500 （內部伺服器錯誤）

    note note
    NOTE
    系統會傳回此錯誤：
    • 當發生無法使用特定程式碼識別的錯誤時
    • 當指定的裝載無效時

    以下列出傳回此錯誤狀態的常見案例，以及產生的錯誤訊息（等寬）：

    • 父資料夾不存在（透過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

    詳細的錯誤訊息通常會以下列方式傳回：

    code language-xml 
    {
  "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-reference

如需詳細的API參考資料，請參閱此處：

其他資源 additional-resources

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

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