Asset Compute Service HTTP API asset-compute-http-api
API的使用僅限於開發目的。 API在開發自訂應用程式時作為內容提供。 Adobe Experience Manager as a Cloud Service使用此API將處理資訊傳遞至自訂應用程式。 如需詳細資訊,請參閱使用資產微服務和處理設定檔。
Asset Compute Service HTTP API的任何使用者端都必須遵循此高階流程:
-
使用者端已布建為IMS組織中的Adobe Developer Console專案。 每個單獨的使用者端(系統或環境)需要其自己的單獨專案,以分隔事件資料流。
-
使用者端使用JWT (服務帳戶)驗證為技術帳戶產生存取權杖。
-
使用者端只會呼叫
/register
一次,以擷取日誌URL。 -
使用者端會針對要產生轉譯的每個資產呼叫
/process
。 呼叫為非同步。 -
使用者端定期輪詢日誌以接收個事件。 成功處理轉譯時(
rendition_created
事件型別)或發生錯誤時(rendition_failed
事件型別),它會接收每個要求轉譯的事件。
adobe-asset-compute-client模組可讓您在Node.js程式碼中輕鬆使用API。
驗證和授權 authentication-and-authorization
所有API都需要存取權杖驗證。 請求必須設定以下標頭:
範圍 scopes
確定以下存取權杖範圍:
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
這些範圍需要訂閱Asset Compute
、I/O Events
和I/O Management API
服務的Adobe Developer Console專案。 個別範圍的劃分如下:
-
基本
- 範圍:
openid,AdobeID
- 範圍:
-
asset compute
- metascope:
asset_compute_meta
- 範圍:
asset_compute,read_organizations
- metascope:
-
Adobe
I/O Events
- metascope:
event_receiver_api
- 範圍:
event_receiver,event_receiver_api
- metascope:
-
Adobe
I/O Management API
- metascope:
ent_adobeio_sdk
- 範圍:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- metascope:
註冊 register
Asset Compute service的每個使用者端(訂閱此服務的唯一Adobe Developer Console專案)都必須註冊,才能提出處理要求。 註冊步驟會傳回從轉譯處理中擷取非同步事件所需的唯一事件日誌。
在其生命週期結束時,使用者端可以取消註冊。
註冊要求 register-request
此API呼叫會設定Asset Compute使用者端並提供事件日誌URL。 此程式是等冪操作,每個使用者端只需要呼叫一次。 可再次呼叫它以擷取日誌URL。
POST
/register
Authorization
x-request-id
登入回應 register-response
application/json
X-Request-Id
X-Request-Id
要求標頭相同或唯一產生的標頭。 用於識別跨系統的請求或支援請求,或兩者皆使用。journal
、ok
或requestId
欄位的JSON物件。HTTP狀態碼為:
-
200成功:要求成功時。
journal
URL會收到有關透過/process
啟動的非同步處理結果的通知。 它會在成功完成時發出rendition_created
個事件的警示,如果處理失敗,則會發出rendition_failed
個事件的警示。code language-json { "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401未獲授權:當要求沒有有效的驗證時發生。 例如,存取權杖無效或API金鑰無效。
-
403禁止存取:當要求沒有有效的授權時發生。 例如,可能是有效的存取Token,但Adobe Developer Console專案(技術帳戶)未訂閱所有必要服務。
-
429太多要求:發生在此使用者端或是系統多載時。 使用者端應以指數回退重試。 內文是空的。
-
4xx錯誤:發生任何其他使用者端錯誤時註冊失敗。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx錯誤:發生於發生任何其他伺服器端錯誤且註冊失敗時。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
取消註冊要求 unregister-request
此API呼叫會取消註冊Asset Compute使用者端。 此取消註冊發生後,就不能再呼叫/process
。 對未註冊的使用者端或尚未註冊的使用者端使用API呼叫會傳回404
錯誤。
POST
/unregister
Authorization
x-request-id
取消登入回應 unregister-response
application/json
X-Request-Id
X-Request-Id
要求標頭相同或唯一產生的標頭。 用於識別跨系統的請求或支援請求。ok
和requestId
欄位的JSON物件。狀態代碼為:
-
200成功:找到並移除登入和日誌時發生。
code language-json { "ok": true, "requestId": "1234567890" }
-
401未獲授權:當要求沒有有效的驗證時發生。 例如,存取權杖無效或API金鑰無效。
-
403禁止存取:當要求沒有有效的授權時發生。 例如,可能是有效的存取Token,但Adobe Developer Console專案(技術帳戶)未訂閱所有必要服務。
-
404找不到:當提供的認證未登入或無效時,就會顯示此狀態。
code language-json { "ok": true, "requestId": "1234567890" }
-
429太多要求:系統超載時發生。 使用者端應以指數回退重試。 內文是空的。
-
4xx錯誤:發生於發生任何其他使用者端錯誤且解除登入失敗時。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx錯誤:發生於發生任何其他伺服器端錯誤且註冊失敗時。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
處理要求 process-request
process
作業會根據請求中的指示,提交將來源資產轉換為多個轉譯的工作。 有關成功完成(事件型別rendition_created
)或任何錯誤(事件型別rendition_failed
)的通知會傳送至事件日誌,必須先使用/register
一次擷取該日誌,然後才能發出任何數量的/process
個請求。 格式錯誤的請求會立即失敗,並產生400錯誤代碼。
使用URL來參考二進位檔案,例如Amazon AWS S3預先簽署的URL或Azure Blob儲存SAS URL。 用於讀取source
資產(GET
URL)和寫入轉譯(PUT
URL)。 使用者端負責產生這些預先簽署的URL。
POST
/process
application/json
Authorization
x-request-id
處理請求JSON process-request-json
/process
的請求本文是具有此高階結構描述的JSON物件:
{
"source": "",
"renditions" : []
}
可用的欄位包括:
source
string
fmt=zip
)。"http://example.com/image.jpg"
source
object
fmt=zip
)選擇性。{"url": "http://example.com/image.jpg", "mimeType": "image/jpeg" }
source
可以是視為URL的<string>
,或可以是具有額外欄位的<object>
。 下列變體類似:
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Source物件欄位 source-object-fields
url
string
"http://example.com/image.jpg"
name
string
content-disposition
標頭中的檔案名稱。 預設為「file」。"image.jpg"
size
number
content-length
標頭。10234
mimetype
string
content-type
標頭。"image/jpeg"
完整的process
要求範例 complete-process-request-example
{
"source": "https://www.adobe.com/content/dam/acom/en/lobby/lobby-bg-bts2017-logged-out-1440x860.jpg",
"renditions" : [{
"name": "image.48x48.png",
"target": "https://some-presigned-put-url-for-image.48x48.png",
"fmt": "png",
"width": 48,
"height": 48
},{
"name": "image.200x200.jpg",
"target": "https://some-presigned-put-url-for-image.200x200.jpg",
"fmt": "jpg",
"width": 200,
"height": 200
},{
"name": "cqdam.xmp.xml",
"target": "https://some-presigned-put-url-for-cqdam.xmp.xml",
"fmt": "xmp"
},{
"name": "cqdam.text.txt",
"target": "https://some-presigned-put-url-for-cqdam.text.txt",
"fmt": "text"
}]
}
處理序回應 process-response
根據基本要求驗證,/process
要求會立即傳回成功或失敗。 實際資產處理為非同步進行。
application/json
X-Request-Id
X-Request-Id
要求標頭相同或唯一產生的標頭。 用於識別跨系統的請求或支援請求。ok
和requestId
欄位的JSON物件。狀態碼:
-
200成功:若已成功提交要求。 回應JSON包含
"ok": true
:code language-json { "ok": true, "requestId": "1234567890" }
-
400無效的請求:如果請求結構不正確(例如,JSON承載中缺少必要欄位)。 回應JSON包含
"ok": false
:code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
401未獲授權:當要求沒有有效的驗證時。 例如,存取權杖無效或API金鑰無效。
-
403禁止存取:要求沒有有效的授權時。 例如,可能是有效的存取Token,但Adobe Developer Console專案(技術帳戶)未訂閱所有必要服務。
-
429太多要求:系統因這個特定使用者端或整體需求而受壓時發生。 使用者端可以使用指數回退重試。 內文是空的。
-
4xx錯誤:發生任何其他使用者端錯誤時。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx錯誤:發生任何其他伺服器端錯誤時。 通常會傳回此類的JSON回應,但並非所有錯誤都有保證:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
大部分使用者端可能會在任何錯誤 上以指數回退重試相同要求,但 設定問題(例如401或403)或無效要求(例如400)除外。 除了429回應方式的定期速率限制以外,暫時性的服務中斷或限制可能會導致5xx錯誤。 之後,建議您在一段時間後重試。
所有JSON回應(如果存在)都包含requestId
,其值與X-Request-Id
標頭相同。 Adobe建議從標頭讀取,因為它一律存在。 requestId
也會在與處理要求相關的所有事件中傳回為requestId
。 使用者端不得對此字串的格式做任何假設。 這是不透明的字串識別碼。
選擇加入後續處理 opt-in-to-post-processing
Asset Compute SDK支援一組基本的影像後處理選項。 自訂背景工作可透過將轉譯物件上的欄位postProcess
設定為true
,明確選擇加入後續處理。
支援的使用案例包括:
- 裁切是矩形的轉譯,其限制由crop.w、crop.h、crop.x和crop.y定義。 在轉譯物件的
instructions.crop
欄位中指定裁切詳細資料。 - 使用寬度、高度或兩者來調整影像大小。
instructions.width
和instructions.height
在轉譯物件中定義它。 若要僅使用寬度或高度來調整大小,請僅設定一個值。 運算服務可節省外觀比例。 - 設定JPEG影像的品質。
instructions.quality
在轉譯物件中定義它。 品質等級為100代表最高品質,而數字較低則表示品質降低。 - 建立交錯影像。
instructions.interlace
在轉譯物件中定義它。 - 設定DPI可調整套用至畫素的比例,以調整案頭出版的演算大小。
instructions.dpi
在轉譯物件中定義它以變更DPI解析度。 但是,若要調整影像大小,使其以不同的解析度大小相同,請使用convertToDpi
指示。 - 調整影像大小,使其演算後的寬度或高度與指定目標解析度(DPI)的原始影像保持相同。
instructions.convertToDpi
在轉譯物件中定義它。
浮水印資產 add-watermark
Asset Compute SDK支援在PNG、JPEG、TIFF和GIF影像檔案中新增浮水印。 依照轉譯上watermark
物件中的轉譯指示新增浮水印。
浮水印會在轉譯後期處理期間完成。 若要為資產加上浮水印,自訂背景工作將轉譯物件上的欄位postProcess
設定為true
,選擇進行後處理。 如果背景工作未選擇加入,則不會套用浮水印,即使浮水印物件已設定在請求中的轉譯物件上。
轉譯指示 rendition-instructions
下列是/process
中renditions
陣列的可用選項。
常用欄位 common-fields
worker
string
https://
URL。 如果此欄位存在,自訂應用程式會建立轉譯。 然後,任何其他集合轉譯欄位都會用於自訂應用程式中。"https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
所產生轉譯的多部分預先簽署URL上傳資訊。 此資訊適用於具有此多部分上傳行為的AEM / Oak直接二進位上傳。
欄位:
urls
:字串陣列,每個預先簽署部分URL各一個minPartSize
:用於一個部分的大小下限= urlmaxPartSize
:單一部分使用的大小上限= url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
轉譯特定欄位 rendition-specific-fields
如需目前支援的檔案格式清單,請參閱支援的檔案格式。
embedBinaryLimit
number
位元組embedBinaryLimit
限制,則會將其放置在雲端儲存空間中的位置,而不會嵌入事件中。3276
width
number
200
height
number
200
如果符合下列條件,則一律會維持外觀比例:
- 同時指定了
width
和height
,然後影像會符合大小,同時維持外觀比例 - 如果只指定
width
或height
,產生的影像會使用對應的維度,同時保持外觀比例 - 如果未指定
width
或height
,則會使用原始影像畫素大小。 這取決於來源型別。 對於某些格式(例如PDF檔案),會使用預設大小。 可以有大小上限。
quality
number
1
到100
範圍內的jpeg品質。 僅適用於影像轉譯。90
xmp
string
interlace
bool
true
,以建立交錯式PNG。 它對其他檔案格式沒有影響。jpegSize
number
quality
設定。 它對其他格式沒有影響。dpi
number
或 object
96
或 { xdpi: 96, ydpi: 96 }
convertToDpi
number
或 object
96
或 { xdpi: 96, ydpi: 96 }
files
array
要包含在ZIP封存檔中的檔案清單(fmt=zip
)。 每個專案都可以是URL字串或具有欄位的物件:
url
:下載檔案的URLpath
:將檔案儲存在ZIP的這個路徑下
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
)。 根據預設,儲存在ZIP中相同路徑下的多個檔案會產生錯誤。 將duplicate
設定為ignore
只會儲存第一個資產,而忽略其餘資產。ignore
浮水印特定欄位 watermark-specific-fields
PNG格式會作為浮水印使用。
scale
number
0.0
到1.0
之間。 1.0
表示浮水印具有原始比例(1:1),較低的值會縮小浮水印大小。0.5
表示原始大小的一半。image
url
非同步事件 asynchronous-events
處理轉譯完成或發生錯誤時,會傳送事件至AdobeI/O Events Journal
。 使用者端必須接聽透過/register
提供的日誌URL。 日誌回應包含event
陣列,每個事件包含一個物件,其中event
欄位包含實際事件裝載。
Asset Compute Service之所有Adobe的I/O Events
型別是asset_compute
。 分錄僅自動訂閱此事件型別,不需要根據Adobe Developer事件型別進一步篩選。 服務特定事件型別可在事件的type
屬性中使用。
事件型別 event-types
rendition_created
rendition_failed
事件屬性 event-attributes
requestId
string
*
/process
的原始要求的要求識別碼,與X-Request-Id
標頭相同。source
object
*
/process
請求的source
。userData
object
*
/process
請求的userData
轉譯(如果已設定)。rendition
object
rendition_*
/process
中傳遞的對應轉譯物件。errorMessage
string
rendition_failed
中繼資料 metadata
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
錯誤原因 error-reasons
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
中提供的預先簽署URL上傳轉譯。 實際轉譯大小可在repo:size
中當做中繼資料使用,使用者端會使用正確數目的預先簽署URL來重新處理此轉譯。GenericError