版本 | 文章連結 |
---|---|
AEM as a Cloud Service | 按一下這裡 |
AEM 6.5 | 本文章 |
瞭解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自訂JSON輸出。
Assets REST API也可讓開發人員透過建立新、更新或刪除現有資產、內容片段和資料夾來修改內容。
Assets REST API:
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
存取:
/api/assets
不需要使用 .model
選擇器。/content/path/to/page
需要使用 .model
選擇器。HTTP 方法決定要執行的操作:
要求內文和/或 URL 參數可用於設定其中一些操作;例如,定義資料夾或資產應由 POST 要求建立。
受支援請求的確切格式定義於 API參考 檔案。
所有要求都是原子的。
這表示後續的(write
)要求無法結合成單一交易,而此交易可能會以單一實體成功或失敗。
外觀 | Assets REST API |
AEM元件 (使用Sling模型的元件) |
支援的使用案例 | 一般用途。 | 針對單頁應用程式(SPA)或任何其他(使用內容)內容的耗用量進行最佳化。 也可以包含佈局資訊。 |
支援的作業 | 建立、讀取、更新、刪除。 根據圖元型別使用其他操作。 |
唯讀. |
存取 | 可直接存取。 使用 範例路徑如下所示: |
需要透過AEM頁面上的AEM元件參考。 使用 範例路徑如下所示: |
安全性 | 可能有多個選項。 建議使用OAuth;可與標準設定分開設定。 |
使用AEM標準設定。 |
架構註解 | 寫入存取權通常可處理製作執行個體。 讀取可能會被導向到發佈執行個體。 |
由於此方法為唯讀,因此通常用於發佈執行個體。 |
輸出 | 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會公開資料夾屬性的存取權,例如其名稱、標題等。 資產會公開為資料夾和子資料夾的子實體。
根據子資產和資料夾的資產型別,子實體清單可能已經包含定義個別子實體的完整屬性集。 或者,在此子圖元清單中,只能為圖元顯示縮減的屬性集。
如果資產已要求,回應會傳回其中繼資料,例如標題、名稱和個別資產結構描述所定義的其他資訊。
資產的二進位資料會公開為型別的SIREN連結 content
.
資產可以有多個轉譯。 這些通常會顯示為子實體,有一個例外是縮圖轉譯,這會公開為型別的連結 thumbnail
( rel="thumbnail"
)。
A 內容片段 是一種特殊型別的資產。 它們可用於存取結構化資料,例如文字、數字、日期等。
由於有許多差異, 標準 資產(例如影像或音訊),則需套用其他規則來處理。
內容片段:
不要公開任何二進位資料。
完全包含在JSON輸出中(在 properties
屬性)。
也視為原子元素,也就是說,元素和變數會作為片段屬性的一部分公開,而不是作為連結或子實體公開。 這樣可讓您有效率地存取片段的裝載。
目前,定義內容片段結構的模型不會透過HTTP API公開。 因此, 消費者 需要瞭解片段的模型(至少是最低要求) — 雖然大多數資訊可以從承載中推斷;以資料型別等。 是定義的一部分。
若要建立內容片段,必須提供模型的(內部存放庫)路徑。
關聯內容目前未公開。
根據您使用的是 AEM 作者環境還是發佈環境,以及您的特定使用案例,使用情況可能會有所不同。
強烈建議將建立繫結至作者執行個體(目前沒有方法可使用此API復寫要發佈的片段)。
都可以從兩者傳遞,因為 AEM 僅以 JSON 格式提供要求的內容。
來自 AEM 作者執行個體的儲存和傳遞操作應該足以滿足防火牆後的媒體庫應用程式的需求。
如果是即時 Web 傳遞,則建議使用 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 的形式傳遞。
可能有兩種類型的讀取操作:
使用方式:
POST /{cfParentPath}/{cfName}
內文必須包含要建立的內容片段的 JSON 表示,包括應在內容片段元素上設定的任何初始內容。必須設定 cq:model
屬性,並且它必須指向有效的內容片段模型。未這麼做會導致錯誤。也必須加上標頭 Content-Type
,其設定為 application/json
。
使用方式:
PUT /{cfParentPath}/{cfName}
內文必須包含給定內容片段要更新之內容的 JSON 表示。
這可以只是內容片段的標題或描述,或單一元素,或所有元素值和/或中繼資料。
使用方式:
DELETE /{cfParentPath}/{cfName}
有幾項限制:
在相關環境中可以看到下列狀態代碼:
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參考資料,請參閱此處:
如需進一步詳細資訊,請參閱: