API HTTP Asset Compute Service asset-compute-http-api
L’utilisation de l’API est limitée à des fins de développement. L’API est fournie à titre de contexte pour le développement d’applications personnalisées. Adobe Experience Manager as a Cloud Service utilise l’API pour transmettre les informations de traitement à une application personnalisée. Pour plus d’informations, voir Utilisation des microservices de ressources et des profils de traitement.
Tout client de l’API HTTP Asset Compute Service doit appliquer ce flux de haut niveau :
-
Un client est configuré en tant que projet Adobe Developer Console dans une organisation IMS. Chaque client (système ou environnement) distinct a besoin de son propre projet pour séparer le flux de données d’événement.
-
Un client génère un jeton d’accès pour le compte technique à l’aide de l’authentification JWT (compte de service).
-
Un client n’appelle
/register
qu’une seule fois pour récupérer l’URL du journal. -
Un client appelle
/process
pour chaque ressource pour laquelle il souhaite générer des rendus. L’appel est asynchrone. -
Un client interroge régulièrement le journal pour recevoir des événements. Il reçoit des événements pour chaque rendu demandé et traité (type d’événement
rendition_created
) ou en cas d’erreur (type d’événementrendition_failed
).
Le module @adobe/asset-compute-client facilite l’utilisation de l’API dans le code Node.js.
Authentification et autorisation authentication-and-authorization
Toutes les API nécessitent une authentification par jeton d’accès. Les requêtes doivent définir les en-têtes suivants :
-
En-tête
Authorization
avec jeton support, qui est le jeton de compte technique, reçu par le biais d’un échange JWT issu du projet Adobe Developer Console. Les portées sont décrites ci-dessous. -
En-tête
x-gw-ims-org-id
avec l’ID d’organisation IMS. -
x-api-key
avec l’ID client du projet Adobe Developers Console.
Portées scopes
Vérifiez les portées suivantes pour le jeton d’accès :
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
Pour cela, le projet Adobe Developer Console doit être abonné aux services Asset Compute
, I/O Events
et I/O Management API
. La répartition des portées individuelles est la suivante :
-
De base
- Portées :
openid,AdobeID
- Portées :
-
Asset Compute
- Metascope :
asset_compute_meta
- Portées :
asset_compute,read_organizations
- Metascope :
-
Adobe I/O Événements
- Metascope :
event_receiver_api
- Portées :
event_receiver,event_receiver_api
- Metascope :
-
API de gestion Adobe I/O
- Metascope :
ent_adobeio_sdk
- Portées :
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- Metascope :
L’enregistrement register
Chaque client d’Asset Compute service (un projet Adobe Developer Console unique, abonné au service) doit s’enregistrer avant de procéder à des demandes de traitement. L’étape d’enregistrement renvoie le journal unique des événements, nécessaire pour récupérer les événements asynchrones issus du traitement du rendu.
À la fin de son cycle de vie, un client peut annuler son enregistrement.
Demande d’enregistrement register-request
Cet appel d’API configure un client Asset Compute et fournit l’URL du journal des événements. Il s’agit d’une opération idempotente (c.-à-d. ayant le même effet si elle est appliquée une ou plusieurs fois), qui ne doit être appelée qu’une seule fois pour chaque client. Elle peut être de nouveau appelée pour récupérer l’URL du journal.
POST
/register
Authorization
x-request-id
Réponse à l’enregistrement register-response
application/json
X-Request-Id
X-Request-Id
ou à celui généré de manière unique. Sert à identifier les requêtes entre systèmes et/ou les demandes d’assistance.journal
, ok
et/ou requestId
.Les codes d’état HTTP sont les suivants :
-
200 Success : lorsque la requête est acceptée. Contient l’URL de
journal
qui doit notifiée des résultats du traitement asynchrone déclenché par/process
(avec un type d’événementrendition_created
en cas de réussite, ourendition_failed
en cas d’échec).code language-json { "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 Unauthorized : survient lorsque la requête ne dispose pas d’une authentification valide. Il peut s’agir, par exemple, d’un jeton d’accès ou d’une clé d’API non valide.
-
403 Forbidden : survient lorsque la demande ne dispose pas d’une autorisation valide. Par exemple, si le jeton d’accès est valide, mais que le projet Adobe Developer Console (compte technique) n’est pas abonné à tous les services requis.
-
429 Too many requests : survient lorsque le système est surchargé de requêtes issues de ce client ou autres. Les clients doivent effectuer un nouvel essai avec un backoff exponentiel (pour diminuer la fréquence du processus). Le corps est vide.
-
Error 4xx : survient en cas d’erreur client, quelle qu’elle soit, et d’échec de l’enregistrement. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx : survient en cas d’erreur côté serveur, quelle qu’elle soit, et d’échec de l’enregistrement. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
Requête d’annulation d’enregistrement unregister-request
Cet appel d’API annule l’enregistrement d’un client Asset Compute. Après cela, il n’est plus possible d’appeler /process
. L’utilisation de l’appel d’API, pour un client non enregistré ou un client à enregistrer, renvoie une erreur 404
.
POST
/unregister
Authorization
x-request-id
Réponse à l’annulation de l’enregistrement unregister-response
application/json
X-Request-Id
X-Request-Id
ou à celui généré de manière unique. Sert à identifier les requêtes entre systèmes et/ou les demandes d’assistance.ok
et requestId
.Les codes d’état sont les suivants :
-
200 Success : survient lorsque l’enregistrement et le journal sont trouvés et supprimés.
code language-json { "ok": true, "requestId": "1234567890" }
-
401 Unauthorized : survient lorsque la requête ne dispose pas d’une authentification valide. Il peut s’agir, par exemple, d’un jeton d’accès ou d’une clé d’API non valide.
-
403 Forbidden : survient lorsque la demande ne dispose pas d’une autorisation valide. Par exemple, si le jeton d’accès est valide, mais que le projet Adobe Developer Console (compte technique) n’est pas abonné à tous les services requis.
-
404 Not found : survient lorsqu’il n’existe aucun enregistrement en cours pour les informations d’identification données.
code language-json { "ok": true, "requestId": "1234567890" }
-
429 Too many requests : survient lorsque le système est surchargé. Les clients doivent effectuer un nouvel essai avec un backoff exponentiel (pour diminuer la fréquence du processus). Le corps est vide.
-
Error 4xx : survient lorsqu’une autre erreur client s’est produite et que l’annulation de l’enregistrement a échoué. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx : survient en cas d’erreur côté serveur, quelle qu’elle soit, et d’échec de l’enregistrement. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
Requête de traitement process-request
L’opération process
lance une tâche chargée de transformer une ressource source en plusieurs rendus, en fonction des instructions contenues dans la requête. Des notifications de succès de l’exécution (type d’événement rendition_created
) ou d’erreur (type d’événement rendition_failed
) sont envoyées à un journal des événements. Celui-ci doit être récupéré en utilisant une fois /register avant de lancer un nombre quelconque de requêtes /process
. Les requêtes incorrectement formulées échouent immédiatement avec un code d’erreur 400.
Les contenus binaires sont référencés à l’aide d’URL, par exemple des URL présignées Amazon AWS S3 ou Azure Blob Storage SAS, à la fois pour la lecture de la ressource source
(URL GET
) et l’écriture des rendus (URL PUT
). Il appartient au client de générer ces URL présignées.
POST
/process
application/json
Authorization
x-request-id
Requête de traitement JSON process-request-json
Le corps de la requête de /process
est un objet JSON dont le schéma est le suivant :
{
"source": "",
"renditions" : []
}
Les champs disponibles sont les suivants :
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" }]
La source
peut être soit une chaîne <string>
, considérée comme une URL, ou un objet (<object>
) avec un champ supplémentaire. Les variantes suivantes sont similaires :
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Champs d’objet source source-object-fields
url
string
"http://example.com/image.jpg"
name
string
content-disposition
de la ressource binaire. La valeur par défaut est « file »."image.jpg"
size
number
content-length
de la ressource binaire.10234
mimetype
string
content-type
de la ressource binaire."image/jpeg"
Exemple de requête process
complète 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"
}]
}
Réponse du traitement process-response
La requête /process
renvoie immédiatement un succès ou un échec en fonction de la validation de la requête de base. Le traitement des ressources se produit de manière asynchrone.
application/json
X-Request-Id
X-Request-Id
ou à celui généré de manière unique. Sert à identifier les requêtes entre systèmes et/ou les demandes d’assistance.ok
et requestId
.Codes d’état :
-
200 Success : si la demande a été envoyée avec succès. La réponse JSON comprend
"ok": true
:code language-json { "ok": true, "requestId": "1234567890" }
-
400 Invalid request : si la requête n’est pas correctement formulée, par exemple s’il manque des champs obligatoires dans le fichier JSON de la requête. La réponse JSON comprend
"ok": false
:code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 Unauthorized : lorsque la requête ne dispose pas d’une authentification valide. Il peut s’agir, par exemple, d’un jeton d’accès ou d’une clé d’API non valide.
-
403 Forbidden : lorsque la demande ne dispose pas d’une autorisation valide. Par exemple, si le jeton d’accès est valide, mais que le projet Adobe Developer Console (compte technique) n’est pas abonné à tous les services requis.
-
429 Too many requests : lorsque le système est surchargé de requêtes issues de ce client ou en général. Les clients peuvent effectuer un nouvel essai avec un backoff exponentiel (pour diminuer la fréquence du processus). Le corps est vide.
-
Error 4xx : en cas d’erreur client, quelle qu’elle soit. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx : survient en cas d’erreur côté serveur, quelle qu’elle soit. Généralement, une réponse JSON de ce type est renvoyée, même si ce n’est pas garanti pour toutes les erreurs :
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
La plupart des clients sont susceptibles de réessayer la même requête avec un backoff exponentiel suite à une erreur, à l’exception des problèmes de configuration, comme 401 ou 403, ou des requêtes non valides comme 400. Outre la limitation du débit normal par le biais de réponses 429, une interruption ou une limitation de service temporaire peut entraîner des erreurs 5xx. Il est dans ce cas conseillé de réessayer après un certain temps.
Toutes les réponses JSON (le cas échéant) incluent la valeur requestId
, identique à celle de l’en-tête X-Request-Id
. Il est recommandé de lire les informations contenues dans l’en-tête, puisqu’il est toujours présent. La valeur requestId
est également renvoyée dans tous les événements relatifs aux requêtes de traitement sous la forme requestId
. Les clients ne doivent pas présumer du format de cette chaîne, car il s’agit d’un identifiant de chaîne opaque.
Souscription au post-traitement opt-in-to-post-processing
Le SDK Asset Compute prend en charge un ensemble d’options de base pour le post-traitement d’images. Les programmes de travail personnalisés peuvent explicitement souscrire au post-traitement en définissant le champ postProcess
de l’objet de rendu sur true
.
Les cas d’utilisation pris en charge sont les suivants :
- Recadrer un rendu pour obtenir un rectangle dont les limites sont définies par crop.w, crop.h, crop.x et crop.y. L’opération est définie par
instructions.crop
dans l’objet de rendu. - Redimensionner les images en utilisant la largeur, la hauteur ou les deux. L’opération est définie par
instructions.width
etinstructions.height
dans l’objet de rendu. Pour redimensionner une image en utilisant uniquement la largeur ou la hauteur, définissez une seule valeur. Compute Service conserve les proportions. - Définir la qualité d’une image JPEG. L’opération est définie par
instructions.quality
dans l’objet de rendu. La meilleure qualité est indiquée par100
et les valeurs inférieures correspondent à une qualité réduite. - Créer des images entrelacées. L’opération est définie par
instructions.interlace
dans l’objet de rendu. - Définir la résolution en ppp pour ajuster la taille des rendus à des fins de publication sur ordinateur en ajustant l’échelle appliquée aux pixels. L’opération est définie par
instructions.dpi
dans l’objet de rendu pour modifier la résolution en ppp. Cependant, pour redimensionner l’image afin qu’elle ait la même taille, mais avec une résolution différente, utilisez les instructionsconvertToDpi
. - Redimensionner l’image pour que sa largeur ou sa hauteur de rendu reste identique à celle de l’image d’origine avec la résolution cible (ppp) spécifiée. L’opération est définie par
instructions.convertToDpi
dans l’objet de rendu.
Mise en filigrane de ressources add-watermark
Le SDK Asset Compute prend en charge l’ajout d’un filigrane aux fichiers d’image PNG, JPEG, TIFF et GIF. Le filigrane est ajouté à la suite des instructions de rendu dans l’objet watermark
.
Le filigrane est appliqué pendant le post-traitement du rendu. Pour les ressources de filigrane, le programme de travail personnalisé opte pour le post-traitement en définissant le champ postProcess
de l’objet de rendu sur true
. Si l’utilisateur n’accepte pas, le filigrane n’est pas appliqué, même si, dans la requête, l’objet de filigrane est défini sur l’objet de rendu.
Instructions de rendu rendition-instructions
Il s’agit des options disponibles pour le tableau renditions
dans /process.
Champs communs common-fields
fmt
string
text
pour l’extraction de texte et xmp
pour l’extraction de métadonnées XMP au format xml. Voir Formats pris en chargepng
worker
string
https://
. Si ce champ est présent, le rendu est créé par une application personnalisée. Tout autre champ de rendu défini est ensuite utilisé dans l’application personnalisée."https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
Informations de chargement d’URL présignées en plusieurs parties pour le rendu généré. Il s’agit d’un chargement AEM/Oak Direct Binary Upload avec ce comportement de chargement en plusieurs parties.
Champs :
urls
: tableau de chaînes, une pour chaque URL de partie pré-signéeminPartSize
: taille minimale à utiliser pour une partie = urlmaxPartSize
: taille maximale à utiliser pour une partie = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
Champs spécifiques au rendu rendition-specific-fields
Pour obtenir la liste des formats de fichiers actuellement pris en charge, voir Formats de fichiers pris en charge.
*
*
embedBinaryLimit
number
en octetsembedBinaryLimit
, il est enregistré dans un espace de stockage dans le cloud et n’est pas incorporé à l’événement.3276
width
number
200
height
number
200
Les proportions sont toujours conservées si :
- Les valeurs
width
etheight
sont spécifiées. L’image est alors adaptée à la taille tout en conservant les proportions - Seule la valeur
width
ouheight
est spécifiée. L’image obtenue utilise la dimension correspondante tout en conservant les proportions - Si aucune valeur
width
ouheight
n’est spécifiée, c’est la taille d’image d’origine en pixels qui est utilisée. Cela dépend du type de source. Pour certains formats, comme les fichiers PDF, une taille par défaut est utilisée. Il peut y avoir une limite de taille maximale.
quality
number
1
et 100
. Applicable uniquement aux rendus d’image.90
xmp
string
interlace
bool
true
. N’a aucun effet sur les autres formats de fichiers.jpegSize
number
quality
. N’a aucun effet sur les autres formats.dpi
number
ou object
96
ou { xdpi: 96, ydpi: 96 }
convertToDpi
number
ou object
96
ou { xdpi: 96, ydpi: 96 }
files
array
Liste des fichiers à inclure dans l’archive ZIP (fmt=zip
). Chaque entrée peut être soit une chaîne URL, soit un objet avec les champs :
url
: URL de téléchargement du fichierpath
: stockage du fichier selon ce chemin d’accès dans le fichier ZIP
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
). Par défaut, une erreur est générée si plusieurs fichiers de l’archive ZIP sont stockés sous le même chemin d’accès. Si vous définissez la valeur de duplicate
sur ignore
, seule la première ressource sera stockée et le reste sera ignoré.ignore
Champs spécifiques aux filigranes watermark-specific-fields
Le format PNG est utilisé comme filigrane.
scale
number
0.0
et 1.0
. 1.0
signifie que le filigrane est à son échelle d’origine (1:1) et que les valeurs inférieures réduisent sa taille.0.5
correspond à la moitié de la taille d’origine.image
url
Événements asynchrones asynchronous-events
Une fois le traitement d’un rendu terminé ou si une erreur se produit, un événement est envoyé à un Adobe I/O journal des événements. Les clients doivent écouter l’URL du journal fournie par le biais de /register. La réponse du journal comprend un tableau event
constitué d’un objet pour chaque événement, dont le champ event
contient la charge utile réelle de l’événement.
Le type Événement Adobe I/O pour tous les événements de l’Asset Compute Service est asset_compute
. Le journal est automatiquement abonné exclusivement à ce type d’événement et il n’est pas nécessaire d’effectuer un filtrage en fonction du type Événement Adobe I/O. Les types d’événements spécifiques au service sont disponibles dans la propriété type
de l’événement.
Types d’événements event-types
rendition_created
rendition_failed
Attributs d’événement event-attributes
date
string
*
requestId
string
*
/process
, identique à l’en-tête X-Request-Id
.source
object
*
source
de la requête /process
.userData
object
*
userData
du rendu issu de la requête /process
, si une définition existe.rendition
object
rendition_*
/process
.errorMessage
string
rendition_failed
Métadonnées metadata
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
Raisons de l’erreur error-reasons
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
. La taille réelle du rendu est disponible sous forme de métadonnées dans repo:size
et peut être utilisée par le client pour traiter à nouveau ce rendu avec le nombre approprié d’URL présignées.GenericError