API HTTP Asset Compute Service
Creado para:
- Desarrollador
El uso de la API se limita a fines de desarrollo. La API se proporciona como contexto al desarrollar aplicaciones personalizadas. Adobe Experience Manager as a Cloud Service usa la API para pasar la información de procesamiento a una aplicación personalizada. Para obtener más información, consulte Usar microservicios de recursos y Perfiles de procesamiento.
Cualquier cliente de la API HTTP Asset Compute Service debe seguir este flujo de alto nivel:
-
Se ha aprovisionado un cliente como un proyecto Adobe Developer Console en una organización IMS. Cada cliente independiente (sistema o entorno) requiere su propio proyecto independiente para separar el flujo de datos de evento.
-
Un cliente genera un token de acceso para la cuenta técnica mediante la autenticación JWT (cuenta de servicio).
-
Un cliente llama a
/register
solo una vez para recuperar la dirección URL del diario. -
Un cliente llama a
/process
para cada recurso para el que desea generar representaciones. La llamada es asincrónica. -
Un cliente sondea regularmente el diario para recibir eventos. Recibe eventos para cada representación solicitada cuando la representación se procesa correctamente (tipo de evento
rendition_created
) o si hay un error (tipo de eventorendition_failed
).
El módulo adobe-asset-compute-client facilita el uso de la API en el código de Node.js.
Autenticación y autorización
Todas las API requieren autenticación de token de acceso. Las solicitudes deben establecer los siguientes encabezados:
-
Authorization
encabezado con token de portador, que es el token de cuenta técnica, recibido a través de intercambio JWT desde el proyecto Adobe Developer Console. Los ámbitos se documentan a continuación. -
Encabezado
x-gw-ims-org-id
con ID de organización de IMS. -
x-api-key
con el ID de cliente del proyecto Adobe Developers Console.
Ámbitos
Asegúrese de que los siguientes ámbitos sean válidos para el token de acceso:
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
Estos ámbitos requieren que el proyecto Adobe Developer Console se suscriba a los servicios Asset Compute
, I/O Events
y I/O Management API
. El desglose de ámbitos individuales es el siguiente:
-
Básica
- ámbitos:
openid,AdobeID
- ámbitos:
-
Asset compute
- metascope:
asset_compute_meta
- ámbitos:
asset_compute,read_organizations
- metascope:
-
Adobe
I/O Events
- metascope:
event_receiver_api
- ámbitos:
event_receiver,event_receiver_api
- metascope:
-
Adobe
I/O Management API
- metascope:
ent_adobeio_sdk
- ámbitos:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- metascope:
Registro
Cada cliente de Asset Compute service (un proyecto único de Adobe Developer Console suscrito al servicio) debe registrarse antes de realizar solicitudes de procesamiento. El paso de registro devuelve el diario de eventos único necesario para recuperar los eventos asincrónicos del procesamiento de la representación.
Al final de su ciclo de vida, un cliente puede anular el registro.
Solicitud de registro
Esta llamada de API configura un cliente Asset Compute y proporciona la dirección URL del diario de eventos. Este proceso es una operación idempotente y solo necesita llamarse una vez para cada cliente. Se puede volver a llamar para recuperar la dirección URL del historial.
POST
/register
Authorization
x-request-id
Registrar respuesta
application/json
X-Request-Id
X-Request-Id
o uno generado de forma única. Se utiliza para identificar solicitudes entre sistemas, solicitudes de soporte o ambas cosas.journal
, ok
o requestId
campos.Los códigos de estado HTTP son:
-
200 con éxito: cuando la solicitud se realiza correctamente. La dirección URL
journal
recibe notificaciones sobre los resultados del procesamiento asincrónico iniciado mediante/process
. Advierte derendition_created
eventos al completarse correctamente, o derendition_failed
eventos si el proceso falla.{ "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 No autorizado: se produce cuando la solicitud no tiene una autenticación válida. Un ejemplo puede ser un token de acceso no válido o una clave de API no válida.
-
403 Prohibido: se produce cuando la solicitud no tiene una autorización válida. Un ejemplo puede ser un token de acceso válido, pero el proyecto de Adobe Developer Console (cuenta técnica) no está suscrito a todos los servicios necesarios.
-
429 Demasiadas solicitudes: se produce cuando este cliente o de otro modo sobrecarga el sistema. Los clientes deben volver a intentarlo con un retroceso exponencial. El cuerpo está vacío.
-
Error de 4xx: cuando hubo cualquier otro error de cliente y el registro falló. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx: se produce cuando se produjo cualquier otro error del lado del servidor y se produjo un error de registro. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Solicitud de cancelación de registro
Esta llamada de API anula el registro de un cliente Asset Compute. Una vez cancelado el registro, ya no es posible llamar a /process
. El uso de la llamada de API para un cliente no registrado o un cliente aún no registrado devuelve un error 404
.
POST
/unregister
Authorization
x-request-id
Anular registro de respuesta
application/json
X-Request-Id
X-Request-Id
o uno generado de forma única. Se utiliza para identificar solicitudes entre sistemas o solicitudes de asistencia.ok
y requestId
campos.Los códigos de estado son:
-
200 con éxito: se produce cuando se encuentra y se quita el registro y el diario.
{ "ok": true, "requestId": "1234567890" }
-
401 No autorizado: se produce cuando la solicitud no tiene una autenticación válida. Un ejemplo puede ser un token de acceso no válido o una clave de API no válida.
-
403 Prohibido: se produce cuando la solicitud no tiene una autorización válida. Un ejemplo puede ser un token de acceso válido, pero el proyecto de Adobe Developer Console (cuenta técnica) no está suscrito a todos los servicios necesarios.
-
404 No encontrado: Este estado aparece cuando las credenciales proporcionadas no están registradas o no son válidas.
{ "ok": true, "requestId": "1234567890" }
-
429 Demasiadas solicitudes: se produce cuando el sistema está sobrecargado. Los clientes deben volver a intentarlo con un retroceso exponencial. El cuerpo está vacío.
-
Error de 4xx: se produce cuando se produjo cualquier otro error de cliente y se produjo un error al anular el registro. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx: se produce cuando se produjo cualquier otro error del lado del servidor y se produjo un error de registro. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Procesar solicitud
La operación process
envía un trabajo que transforma un recurso de origen en varias representaciones, según las instrucciones de la solicitud. Las notificaciones sobre la finalización correcta (tipo de evento rendition_created
) o cualquier error (tipo de evento rendition_failed
) se envían a un diario de eventos que debe recuperarse mediante /register
una vez antes de realizar cualquier número de /process
solicitudes. Las solicitudes formadas incorrectamente generan un error 400.
Se hace referencia a los binarios mediante direcciones URL, como URL prefirmadas de Amazon AWS S3 o URL de SAS de almacenamiento de Azure Blob. Se usa tanto para leer el recurso source
(GET
direcciones URL) como para escribir las representaciones (PUT
direcciones URL). El cliente es responsable de generar estas direcciones URL prefirmadas.
POST
/process
application/json
Authorization
x-request-id
Solicitud de proceso JSON
El cuerpo de la solicitud de /process
es un objeto JSON con este esquema de alto nivel:
{
"source": "",
"renditions" : []
}
Los campos disponibles son:
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
puede ser un <string>
que se vea como una dirección URL o puede ser un <object>
con un campo adicional. Las siguientes variantes son similares:
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Campos de objeto de Source
url
string
"http://example.com/image.jpg"
name
string
content-disposition
del recurso binario. El valor predeterminado es "archivo"."image.jpg"
size
number
content-length
del recurso binario.10234
mimetype
string
content-type
del recurso binario."image/jpeg"
Un ejemplo de solicitud process
completa
{
"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"
}]
}
Respuesta del proceso
La solicitud /process
se devuelve inmediatamente con un resultado correcto o erróneo según la validación básica de la solicitud. El procesamiento real de recursos se produce de forma asíncrona.
application/json
X-Request-Id
X-Request-Id
o uno generado de forma única. Se utiliza para identificar solicitudes entre sistemas o solicitudes de asistencia.ok
y requestId
campos.Códigos de estado:
-
200 con éxito: si la solicitud se envió correctamente. El JSON de respuesta incluye
"ok": true
:{ "ok": true, "requestId": "1234567890" }
-
400 Solicitud no válida: Si la solicitud está estructurada incorrectamente, por ejemplo, si carece de campos obligatorios en la carga útil JSON. El JSON de respuesta incluye
"ok": false
:{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 No autorizado: Cuando la solicitud no tiene una autenticación válida. Un ejemplo puede ser un token de acceso no válido o una clave de API no válida.
-
403 Prohibido: Cuando la solicitud no tiene una autorización válida. Un ejemplo puede ser un token de acceso válido, pero el proyecto de Adobe Developer Console (cuenta técnica) no está suscrito a todos los servicios necesarios.
-
429 Demasiadas solicitudes: Se produce cuando el sistema está sobrecargado, ya sea debido a este cliente en particular o a una demanda general. Los clientes pueden volver a intentarlo con un retroceso exponencial. El cuerpo está vacío.
-
Error de 4xx: cuando había algún otro error de cliente. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
Error 5xx: cuando había algún otro error del lado del servidor. Normalmente se devuelve una respuesta JSON como esta, aunque no está garantizado para todos los errores:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Es probable que la mayoría de los clientes prefieran reintentar la misma solicitud con retroceso exponencial en cualquier error excepto problemas de configuración como 401 o 403, o solicitudes no válidas como 400. Aparte de la limitación regular de la velocidad mediante respuestas 429, una interrupción temporal del servicio o una limitación podría provocar errores 5xx. Entonces, sería aconsejable volver a intentarlo después de un periodo de tiempo.
Todas las respuestas JSON (si están presentes) incluyen requestId
, que es el mismo valor que el encabezado X-Request-Id
. El Adobe recomienda leer del encabezado porque siempre está presente. El requestId
también se devuelve en todos los eventos relacionados con el procesamiento de solicitudes como requestId
. Los clientes no deben suponer el formato de esta cadena. Es un identificador de cadena opaco.
Inclusión en el posprocesamiento
El SDK de Asset compute admite un conjunto de opciones básicas de procesamiento posterior de imágenes. Los trabajadores personalizados pueden incluirse explícitamente en el posprocesamiento estableciendo el campo postProcess
en el objeto de representación en true
.
Los casos de uso admitidos son:
- Recortar es una representación en un rectángulo cuyos límites están definidos por crop.w, crop.h, crop.x y crop.y. Los detalles de recorte se especifican en el campo
instructions.crop
del objeto de representación. - Cambie el tamaño de las imágenes mediante los valores de anchura, altura o ambos.
instructions.width
yinstructions.height
lo definen en el objeto de representación. Para cambiar el tamaño sólo con anchura o altura, defina sólo un valor. Compute Service conserva la relación de aspecto. - Establezca la calidad de una imagen JPEG.
instructions.quality
lo define en el objeto de representación. Un nivel de calidad de 100 representa la calidad más alta, mientras que números más bajos significan una disminución en la calidad. - Cree imágenes entrelazadas.
instructions.interlace
lo define en el objeto de representación. - Establezca PPP para ajustar el tamaño procesado para la publicación en el escritorio ajustando la escala aplicada a los píxeles. El
instructions.dpi
lo define en el objeto de representación para cambiar la resolución de los ppp. Sin embargo, para cambiar el tamaño de la imagen de modo que tenga el mismo tamaño con una resolución diferente, siga las instrucciones deconvertToDpi
. - Cambie el tamaño de la imagen de modo que la anchura o altura procesadas sean las mismas que las originales con la resolución de destino especificada (PPP).
instructions.convertToDpi
lo define en el objeto de representación.
Recursos de marca de agua
El SDK de Asset compute admite la adición de una marca de agua a los archivos de imagen PNG, JPEG, TIFF y GIF. La marca de agua se agrega siguiendo las instrucciones de representación del objeto watermark
de la representación.
La marca de agua se realiza durante el procesamiento posterior de la representación. Para marcar los recursos, el trabajador personalizado opta por el posprocesamiento al establecer el campo postProcess
en el objeto de representación en true
. Si el trabajador no selecciona, la marca de agua no se aplica, incluso si el objeto de marca de agua está establecido en el objeto de representación de la solicitud.
Instrucciones de representación
Las siguientes son las opciones disponibles para la matriz renditions
en /process
.
Campos comunes
fmt
string
text
para la extracción de texto y xmp
para la extracción de metadatos de como xml. Ver formatos compatiblespng
worker
string
https://
. Si este campo está presente, una aplicación personalizada crea la representación. A continuación, se utiliza cualquier otro campo de representación definido en la aplicación personalizada."https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
Información de carga de URL firmada previamente de varias partes para la representación generada. AEM Esta información es para / Carga binaria directa de Oak con este comportamiento de carga multiparte.
Campos:
urls
: matriz de cadenas, una para cada URL de parte firmada previamenteminPartSize
: el tamaño mínimo que se va a usar para una parte = urlmaxPartSize
: el tamaño máximo que se va a usar para una parte = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
Campos específicos de representación
Para obtener una lista de los formatos de archivo admitidos actualmente, consulte formatos de archivo admitidos.
embedBinaryLimit
number
en bytesembedBinaryLimit
, se coloca en una ubicación del almacenamiento en la nube y no está incrustada en el evento.3276
width
number
200
height
number
200
La relación de aspecto se mantiene siempre si:
- Se especificaron
width
yheight
, y la imagen se ajustará al tamaño sin perder la relación de aspecto - Si solo se especifica
width
oheight
, la imagen resultante utilizará la dimensión correspondiente y mantendrá la relación de aspecto - Si no se especifica
width
oheight
, se utilizará el tamaño de píxel de la imagen original. Depende del tipo de origen. En algunos formatos, como los archivos de PDF, se utiliza un tamaño predeterminado. Puede haber un límite de tamaño máximo.
quality
number
1
a 100
. Aplicable solo para representaciones de imágenes.90
xmp
string
interlace
bool
true
. No afecta a otros formatos de archivo.jpegSize
number
quality
. No afecta a otros formatos.dpi
number
o object
96
o { xdpi: 96, ydpi: 96 }
convertToDpi
number
o object
96
o { xdpi: 96, ydpi: 96 }
files
array
Lista de archivos para incluir en el archivo ZIP (fmt=zip
). Cada entrada puede ser una cadena URL o un objeto con los campos:
url
: URL para descargar el archivopath
: almacena el archivo en esta ruta de acceso en el ZIP
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
). De forma predeterminada, varios archivos almacenados en la misma ruta en el ZIP generan un error. Si se establece duplicate
en ignore
, solo se almacenará el primer recurso y se omitirá el resto.ignore
Campos específicos de marcas de agua
El formato PNG se utiliza como marca de agua.
scale
number
0.0
y 1.0
. 1.0
significa que la marca de agua tiene su escala original (1:1) y los valores inferiores reducen el tamaño de la marca de agua.0.5
significa la mitad del tamaño original.image
url
Eventos asíncronos
Cuando finaliza el procesamiento de una representación o se produce un error, se envía un evento a un Adobe I/O Events Journal
. Los clientes deben escuchar la dirección URL del diario proporcionada a través de /register
. La respuesta del diario incluye una matriz event
que consta de un objeto para cada evento, de los cuales el campo event
incluye la carga útil del evento real.
El tipo de Adobe I/O Events
para todos los eventos de Asset Compute Service es asset_compute
. El historial solo se suscribe automáticamente a este tipo de evento y no se requiere ningún otro filtro basado en el tipo de evento Adobe Developer. Los tipos de eventos específicos del servicio están disponibles en la propiedad type
del evento.
Tipos de eventos
rendition_created
rendition_failed
Atributos de evento
date
string
*
requestId
string
*
/process
, igual que el encabezado de X-Request-Id
.source
object
*
source
de la solicitud /process
.userData
object
*
userData
de la representación de la solicitud /process
si está establecido.rendition
object
rendition_*
/process
.errorMessage
string
rendition_failed
Metadatos
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
Motivos de error
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
. El tamaño real de la representación está disponible como metadatos en repo:size
y el cliente lo usa para volver a procesar esta representación con el número correcto de direcciones URL firmadas previamente.GenericError