AEM Assets HTTP API中的內容片段支援 content-fragments-support-in-aem-assets-http-api
概觀 overview
瞭解Assets HTTP API支援內容片段，這是Adobe Experience Manager (AEM) Headless傳送功能的重要一環。
Assets REST API可讓Adobe Experience Manager as a Cloud Service的開發人員透過CRUD （建立、讀取、更新、刪除）作業，直接透過HTTP API存取內容(儲存在AEM中)。
此API可讓您藉由向Adobe Experience Manager as a Cloud Service前端應用程式提供內容服務，以將JavaScript當作Headless CMS （內容管理系統）來運作。 或任何可執行HTTP要求及處理JSON回應的其他應用程式。
例如，單頁應用程式(SPA) （框架式或自訂）需要透過HTTP API提供的內容，通常為JSON格式。
雖然AEM核心元件提供可自訂的API，可提供此用途的必要讀取作業，且可自訂其JSON輸出，但實作時確實需要AEM WCM （Web內容管理）技術。 這是因為它們必須託管在基於專用AEM範本的頁面中。 並非每個SPA開發組織都能直接存取這些知識。
此時可使用Assets REST API。 它可讓開發人員直接存取資產（例如影像和內容片段），而不需要先將資產內嵌在頁面中，並以序列化JSON格式傳送其內容。
Assets REST API也可讓開發人員透過建立新、更新或刪除現有資產、內容片段和資料夾，來修改內容。
Assets REST API：
先決條件 prerequisites
Adobe Experience Manager as a Cloud Service 最新版本的每個開箱即用安裝中都有提供 Assets REST API。
重要概念 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
/api/assets不需要 使用.model選擇器。/content/path/to/page需要 使用.model選擇器。
HTTP 方法決定要執行的操作：
- GET - 檢索資產或資料夾的 JSON 表示
- POST — 建立資產或資料夾
- PUT - 更新資產或資料夾的屬性
- DELETE - 刪除資產或資料夾
在API參考檔案中定義了支援要求的確切格式。
異動行為 transactional-behavior
所有要求都是原子的。
這表示後續(write)要求無法合併成單一交易，而單一實體可能會成功或失敗。
AEM (Assets) REST API與AEM元件 aem-assets-rest-api-versus-aem-components
（使用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；可與標準設定分開設定。
寫入存取權通常可處理作者例項。
系統也可能將讀取導向至Publish執行個體。
安全性 security
如果是在沒有特定驗證需求的環境中使用Assets REST API，則必須正確設定AEM CORS篩選器。
在有特定驗證需求的環境中，建議使用OAuth。
可用功能 available-features
內容片段是特定型別的資產，請參閱使用內容片段。
如需透過API提供的功能詳細資訊，請參閱：
- Assets REST API
- 實體型別，其中說明每個支援型別的特定功能（與內容片段相關）
分頁 paging
Assets REST API支援透過URL引數來分頁(針對GET請求)：
offset— 要擷取的第一個（子項）實體數目limit— 傳回的實體數上限
回應包含分頁資訊，作為SIREN輸出之properties區段的一部分。 此srn:paging屬性包含要求中所指定的（子）實體總數( total)、位移和限制( offset、limit)。
範例：分頁 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會顯示為資料夾和子資料夾的子專案。
Assets assets
如果請求資產，回應會傳回其中繼資料，例如標題、名稱和個別資產結構描述所定義的其他資訊。
資產的二進位資料會公開為型別content的SIREN連結。
Assets可以有多個轉譯。 這些通常會顯示為子實體，其中一個例外是縮圖轉譯，這會公開為型別thumbnail ( rel="thumbnail")的連結。
內容片段 content-fragments
內容片段是特殊型別的資產。 它們可用於存取結構化資料，例如文字、數字、日期等。
由於 標準 資產（例如影像或音訊）有幾項差異，因此處理這些資產需套用其他規則。
表示 representation
內容片段：
-
不要公開任何二進位資料。
-
包含在JSON輸出中（在
properties屬性內）。 -
它們也被視為原子元素。 也就是說，元素和變數會作為片段屬性的一部分顯示，而不是作為連結或子實體顯示。 這樣可讓您有效率地存取片段的裝載。
內容模型和內容片段 content-models-and-content-fragments
目前，定義內容片段結構的模型不會透過HTTP API公開。 因此，消費者 必須知道片段的模型（至少是最低限度） — 雖然大多數資訊可以從承載中推斷；因為資料型別等都是定義的一部分。
若要建立內容片段，必須提供模型的（內部存放庫）路徑。
相關聯的內容 associated-content
關聯內容未公開。
使用 using
使用方式會因您使用的是AEM Author或Publish環境以及您的特定使用案例而有所不同。
-
建議將建立繫結至作者執行個體()，目前沒有方法可使用此API將片段復寫至發佈)。
-
都可以從兩者傳遞，因為 AEM 僅以 JSON 格式提供要求的內容。
-
對於防火牆後的媒體程式庫應用程式，AEM編寫執行個體的儲存和傳送應已足夠。
-
若要進行即時網頁傳送，建議使用AEM Publish執行個體。
-
/api的存取。限制 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 specifiedCannot 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 elementCould 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
如需詳細資訊，請參閱：