Asset Compute Service HTTP API
- トピック:
- Asset Compute マイクロサービス
作成対象:
- 開発者
この API の使用は開発目的に限られています。この API は、カスタムアプリケーションの開発用として提供されます。Adobe Experience Manager as a Cloud Service では、この API を使用して処理情報をカスタムアプリケーションに渡します。詳しくは、アセットマイクロサービスと処理プロファイルの使用を参照してください。
Asset Compute Service HTTP API のクライアントはすべて、次の大まかなフローに従う必要があります。
-
クライアントが IMS 組織で Adobe Developer Console プロジェクトとしてプロビジョニングされます。イベントデータフローを分離するために、クライアント(システムまたは環境)ごとに個別のプロジェクトが必要です。
-
クライアントが、JWT(サービスアカウント)認証を使用して、テクニカルアカウントのアクセストークンを生成します。
-
クライアントが
/register
を 1 回だけ呼び出して、ジャーナル URL を取得します。 -
クライアントが、レンディションの生成対象となるアセットごとに
/process
を呼び出します。この呼び出しは非同期的に実行されます。 -
クライアントがジャーナルを定期的にポーリングして、イベントを受け取ります。レンディションが正常に処理された場合(
rendition_created
イベントタイプ)またはエラーが発生した場合(rendition_failed
イベントタイプ)に、要求されたレンディションごとにイベントを受け取ります。
adobe-asset-compute-client モジュールを利用すると、Node.js コードで API を簡単に使用できます。
認証と承認
すべての API にはアクセストークン認証が必要です。リクエストには、次のヘッダーを設定する必要があります。
スコープ
アクセストークンのスコープを確認します。
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
これらのスコープでは、Adobe Developer Console プロジェクトで Asset Compute
、I/O Events
、I/O Management API
の各サービスを購読する必要があります。個々のスコープの内訳は次のとおりです。
-
基本
- スコープ:
openid,AdobeID
- スコープ:
-
Asset Compute
- メタスコープ:
asset_compute_meta
- スコープ:
asset_compute,read_organizations
- メタスコープ:
-
アドビ
I/O Events
- メタスコープ:
event_receiver_api
- スコープ:
event_receiver,event_receiver_api
- メタスコープ:
-
アドビ
I/O Management API
- メタスコープ:
ent_adobeio_sdk
- スコープ:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- メタスコープ:
登録
Asset Compute service の各クライアント(このサービスをサブスクライブしている一意の Adobe Developer Console プロジェクト)は、処理リクエストをおこなう前に登録する必要があります。登録ステップは、レンディション処理から非同期イベントを取得するために必要な固有のイベントジャーナルを返します。
ライフサイクルの終わりに、クライアントは登録解除できます。
登録リクエスト
この API 呼び出しは、Asset Compute クライアントを設定し、イベントジャーナル URL を提供します。このプロセスはべき等性がある操作であり、クライアントごとに 1 回だけ呼び出す必要があります。このメソッドを再度呼び出せば、ジャーナル URL を取得できます。
POST
/register
Authorization
x-request-id
登録応答
application/json
X-Request-Id
X-Request-Id
リクエストヘッダーと同じか、一意に生成されたヘッダー。複数のシステムやサポートリクエスト、またはその両方を識別するために使用します。journal
、ok
、requestId
のいずれかのフィールドを含んだ JSON オブジェクト。HTTP ステータスコードは次のとおりです。
-
200 Success:リクエストが成功した場合。
journal
URL は、/process
経由で開始された非同期処理の結果に関する通知を受け取ります。正常に完了するとrendition_created
イベント、プロセスが失敗した場合はrendition_failed
イベントのアラートが表示されます。{ "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 Unauthorized:有効な認証がリクエストにない場合に発生します。例えば、無効なアクセストークンや無効な API キーなどがあります。
-
403 Forbidden:有効な承認がリクエストにない場合に発生します。例えば、アクセストークンが有効でも、Adobe Developer Console プロジェクト(テクニカルアカウント)が、必要なすべてのサービスをサブスクライブしていない場合などです。
-
429 Too many requests:このクライアントまたはそれ以外の場合でシステムが過負荷状態になると発生します。クライアントは指数関数的バックオフを使用して再試行する必要があります。本文は空です。
-
4xx エラー:その他の任意のクライアントエラーが発生し、登録に失敗した場合。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx エラー:その他の任意のサーバー側エラーが発生し、登録に失敗した場合に発生します。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
登録解除リクエスト
この API 呼び出しは、Asset Compute クライアントの登録を解除します。この登録解除が行われると、/process
を呼び出すことができなくなります。未登録のクライアントに対してこの API 呼び出しを使用すると、404
エラーが返されます。
POST
/unregister
Authorization
x-request-id
登録解除応答
application/json
X-Request-Id
X-Request-Id
リクエストヘッダーと同じか、一意に生成されたヘッダー。複数のシステムやサポートリクエストにわたってリクエストを識別するために使用されます。ok
フィールドと requestId
フィールドを含んだ JSON オブジェクト。ステータスコードは次のとおりです。
-
200 Success:登録とジャーナルが見つかり、削除されたときに発生します。
{ "ok": true, "requestId": "1234567890" }
-
401 Unauthorized:有効な認証がリクエストにない場合に発生します。例えば、無効なアクセストークンや無効な API キーなどがあります。
-
403 Forbidden:有効な承認がリクエストにない場合に発生します。例えば、アクセストークンが有効でも、Adobe Developer Console プロジェクト(テクニカルアカウント)が、必要なすべてのサービスをサブスクライブしていない場合などです。
-
404 Not found:このステータスは、指定した資格情報が登録解除されたか無効な場合に表示されます。
{ "ok": true, "requestId": "1234567890" }
-
429 Too many requests:システムが過負荷になっている場合に発生します。クライアントは指数関数的バックオフを使用して再試行する必要があります。本文は空です。
-
4xx エラー:その他の任意のクライアントエラーが発生し、登録解除に失敗した場合に発生します。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx エラー:その他の任意のサーバー側エラーが発生し、登録に失敗した場合に発生します。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
処理リクエスト
process
操作では、リクエスト内の指示に基づいてソースアセットを複数のレンディションに変換するジョブを送信します。正常完了(イベントタイプ rendition_created
)または任意のエラー(イベントタイプ rendition_failed
)に関する通知がイベントジャーナルに送信されます。このジャーナルは、/process
リクエストを行う前に /register
を 1 回使用して取得する必要があります。形式が正しくないリクエストは即座に失敗し、400 エラーコードが返されます。
バイナリは、Amazon AWS S3 の事前署名済み URL や Azure Blob Storage SAS URL などの URL を使用して参照されます。source
アセットの読み取り(GET
URL)とレンディションの書き込み(PUT
URL)の両方に使用されます。これらの署名済み URL の生成はクライアントが担当します。
POST
/process
application/json
Authorization
x-request-id
処理リクエスト 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" }
renditions
array
[{ "target": "https://....", "fmt": "png" }]
source
は、URL と見なされる <string>
か、追加フィールドを含んだ <object>
のいずれかにすることができます。次のような似たバリエーションがあります。
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
source オブジェクトのフィールド
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
リクエストの例
{
"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
リクエストは、基本的なリクエスト検証に基づいて、成功または失敗を即座に返します。実際のアセット処理は非同期でおこなわれます。
application/json
X-Request-Id
X-Request-Id
リクエストヘッダーと同じか、一意に生成されたヘッダー。複数のシステムやサポートリクエストにわたってリクエストを識別するために使用されます。ok
フィールドと requestId
フィールドを含んだ JSON オブジェクト。ステータスコード:
-
200 Success:リクエストが正常に送信された場合。応答 JSON には
"ok": true
が含まれています。{ "ok": true, "requestId": "1234567890" }
-
400 Invalid request:リクエストが不適切に構造化されている場合(例えば、JSON ペイロードに必須フィールドがない場合)。応答 JSON には
"ok": false
が含まれています。{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 Unauthorized:有効な認証がリクエストにない場合です。例えば、無効なアクセストークンや無効な API キーなどがあります。
-
403 Forbidden:有効な承認がリクエストにない場合です。例えば、アクセストークンが有効でも、Adobe Developer Console プロジェクト(テクニカルアカウント)が、必要なすべてのサービスをサブスクライブしていない場合などです。
-
429 Too many requests:この特定のクライアントまたは全体的な需要により、システムが過負荷になった際に発生します。クライアントは指数関数的バックオフを使用して再試行できます。本文は空です。
-
4xx エラー:その他の任意のクライアントエラーが発生した場合です。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx エラー:その他の任意のサーバー側エラーが発生した場合です。通常、次のような JSON 応答が返されますが、これはすべてのエラーに対して保証されているわけではありません。
{ "ok": false, "requestId": "1234567890", "message": "error message" }
ほとんどのクライアントは、401 や 403 などの設定の問題や、400 などの無効なリクエストを 除き、エラーが発生すると指数バックオフを使用して同じリクエストを再試行する傾向があります。429 応答による通常のレート制限とは別に、一時的なサービス停止または制限により、5xx エラーが発生する可能性があります。その場合は、しばらくしてから再試行することをお勧めします。
すべての JSON 応答(存在する場合)には、X-Request-Id
ヘッダーと同じ値の requestId
が含まれます。アドビでは、ヘッダーが常に存在するたので、ヘッダーから読み取ることをお勧めします。また、requestId
は、処理リクエストに関連するすべてのイベントでも requestId
として返されます。クライアントは、この文字列の形式についていかなる仮定も行ってはなりません。これは、不透明な文字列識別子です。
後処理へのオプトイン
Asset Compute SDK では、一連の基本的な画像後処理オプションをサポートしています。カスタムワーカーは、レンディションオブジェクトの postProcess
フィールドを true
に設定して、後処理を明示的にオプトインすることができます。
次のユースケースがサポートされています。
- 切り抜きは、crop.w、crop.h、crop.x、crop.y による制限が定義された長方形へのレンディションです。切り抜きの詳細は、レンディションオブジェクトの
instructions.crop
フィールドで指定します。 - 幅、高さまたはその両方を使用して画像のサイズを変更する。
instructions.width
とinstructions.height
では、レンディションオブジェクト内で定義します。幅または高さのみを使用してサイズを変更する場合は、一方の値だけを設定します。Compute Service では縦横比を保持します。 - JPEG 画像の画質を設定する。
instructions.quality
では、レンディションオブジェクト内で定義します。画質レベル 100 は最高画質を表し、数値が小さいほど画質が低下します。 - インターレース画像を作成する。
instructions.interlace
では、レンディションオブジェクト内で定義します。 - ピクセルに適用するスケールを調整することで、DPI を設定してデスクトップパブリッシング用にレンダリングサイズを調整する。
instructions.dpi
では、レンディションオブジェクト内で定義し、DPI 解像度を変更します。ただし、異なる解像度で同じサイズになるように画像のサイズを変更する場合は、convertToDpi
指示を使用します。 - レンダリング後の幅または高さが指定のターゲット解像度(DPI)で元の画像と同じになるように画像のサイズを変更する。
instructions.convertToDpi
では、レンディションオブジェクト内で定義します。
アセットへの透かしの適用
Asset Compute SDK では、PNG、JPEG、TIFF、GIF の各画像ファイルへの透かしの追加をサポートしています。透かしは、レンディションの watermark
オブジェクトのレンディション指示に従って追加されます。
透かしの追加はレンディションの後処理中におこなわれます。アセットに透かしを追加するには、レンディションオブジェクトの postProcess
フィールドを true
に設定して、カスタムワーカーが後処理をオプトインします。ワーカーがオプトインしない場合、リクエストのレンディションオブジェクトに透かしオブジェクトが設定されている場合でも、透かしは適用されません。
レンディション指示
以下は、/process
の renditions
配列で使用可能なオプションです。
共通のフィールド
fmt
string
png
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 ごとに 1 つの文字列が割り当てられます。minPartSize
:1 つのパート(URL)に使用する最小サイズmaxPartSize
:1 つのパート(URL)に使用する最大サイズ
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
レンディション固有のフィールド
現在サポートされているファイル形式の一覧については、サポートされているファイル形式を参照してください。
embedBinaryLimit
number
(バイト単位)embedBinaryLimit
を超える場合、レンディションはクラウドストレージ内の場所に配置され、イベントには埋め込まれません。3276
width
number
200
height
number
200
次の場合、縦横比は常に維持されます。
width
とheight
の両方を指定した場合、画像は縦横比を維持しながら指定のサイズに合わせて調整されますwidth
かheight
のどちらかを指定した場合、結果として生成される画像では縦横比を維持しながら、対応する寸法が使用されますwidth
もheight
も指定しなかった場合は、元の画像のピクセルサイズが使用されます。ソースのタイプによって異なります。PDF ファイルなど、一部の形式では、デフォルトサイズが使用されます。最大サイズの制限が設定されていることがあります。
quality
number
1
~100
の範囲で指定します。画像レンディションの場合にのみ適用できます。90
xmp
string
interlace
bool
true
に設定すると、インターレースの PNG、GIF、プログレッシブ JPEG のいずれかが作成されます。他のファイル形式には影響しません。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
透かし固有のフィールド
PNG 形式が透かしとして使用されます。
scale
number
0.0
~1.0
)。1.0
は、透かしが元画像のサイズと同じ(1:1)であることを意味します。この値を小さくすると透かしのサイズが小さくなります。0.5
の場合は、元のサイズの半分であることを意味します。image
url
非同期イベント
レンディションの処理が完了した場合、またはエラーが発生した場合は、Adobe I/O Events Journal
にイベントが送信されます。クライアントは、/register
を通じて提供されたジャーナル URL をリッスンする必要があります。ジャーナル応答は event
配列を含んでいます。その要素は各イベントに対応する 1 つのオブジェクトで、そのオブジェクトの event
フィールドに実際のイベントペイロードが含まれています。
Asset Compute Service のすべてのイベントに対する Adobe I/O Events
タイプは asset_compute
です。ジャーナルは、このイベントタイプのみを自動的にサブスクライブし、Adobe Developer イベントタイプに基づいてさらにフィルタリングする必要はありません。このサービス固有のイベントタイプは、イベントの type
プロパティで得られます。
イベントタイプ
rendition_created
rendition_failed
イベント属性
requestId
string
*
/process
に対する元のリクエストのリクエスト ID(X-Request-Id
ヘッダーと同じ)。source
object
*
/process
リクエストの source
。userData
object
*
/process
リクエストから生成されるレンディションの userData
。rendition
object
rendition_*
/process
に渡された対応するレンディションオブジェクト。errorMessage
string
rendition_failed
メタデータ
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
エラー理由
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
で指定された署名済み URL を使用してレンディションをアップロードできませんでした。実際のレンディションサイズは、repo:size
でメタデータとして提供されています。クライアントはこれを使用して、適切な数の署名済み URL でこのレンディションを再処理します。GenericError