Asset Compute Service API HTTP asset-compute-http-api
O uso da API é limitado a fins de desenvolvimento. A API é fornecida como um contexto ao desenvolver aplicativos personalizados. Adobe Experience Manager as a Cloud Service O usa a API para transmitir as informações de processamento a um aplicativo personalizado. Para obter mais informações, consulte Usar microsserviços de ativos e perfis de processamento.
Qualquer cliente do Asset Compute Service A API HTTP deve seguir esse fluxo de alto nível:
-
Um cliente é provisionado como Adobe Developer Console em uma organização IMS. Cada cliente separado (sistema ou ambiente) requer seu próprio projeto separado para separar o fluxo de dados do evento.
-
Um cliente gera um token de acesso para a conta técnica usando o Autenticação JWT (conta de serviço).
-
Um cliente chama
/register
recupere o URL do diário apenas uma vez. -
Um cliente chama
/process
para cada ativo para o qual deseja gerar representações. A chamada é assíncrona. -
Um cliente faz polling regular do journal para receber eventos. Ele recebe eventos para cada representação solicitada quando ela é processada com êxito (
rendition_created
tipo de evento) ou se houver um erro (rendition_failed
tipo de evento).
A variável @adobe/asset-compute-client O módulo facilita o uso da API no código Node.js.
Autenticação e autorização authentication-and-authorization
Todas as APIs exigem autenticação de token de acesso. As solicitações devem definir os seguintes cabeçalhos:
-
Authorization
cabeçalho com token de portador, que é o token de conta técnica, recebido via Troca de JWT do projeto do Adobe Developer Console. A variável escopos estão documentados abaixo. -
x-gw-ims-org-id
cabeçalho com a ID da organização IMS. -
x-api-key
com a ID do cliente do Adobe Developers Console projeto.
Escopos scopes
Verifique os seguintes escopos para o token de acesso:
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
Estes requisitos exigem a Adobe Developer Console projeto que deve ser assinado Asset Compute
, I/O Events
, e I/O Management API
serviços. O detalhamento de escopos individuais é:
-
Básico
- escopos:
openid,AdobeID
- escopos:
-
Asset compute
- metascope:
asset_compute_meta
- escopos:
asset_compute,read_organizations
- metascope:
-
Adobe I/O Eventos
- metascope:
event_receiver_api
- escopos:
event_receiver,event_receiver_api
- metascope:
-
Adobe I/O API de gerenciamento
- metascope:
ent_adobeio_sdk
- escopos:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- metascope:
Registro register
Cada cliente do Asset Compute service - um único Adobe Developer Console projeto inscrito no serviço - deve registrar antes de fazer solicitações de processamento. A etapa de registro retorna o diário de eventos exclusivo, que é necessário para recuperar os eventos assíncronos do processamento de representação.
No final de seu ciclo de vida, um cliente pode cancelar registro.
Registrar solicitação register-request
Esta chamada de API configura um Asset Compute e fornece o URL do diário de eventos. Esta é uma operação idempotente e só precisa ser chamada uma vez para cada cliente. Ele pode ser chamado novamente para recuperar o URL do diário.
POST
/register
Authorization
x-request-id
Registrar resposta register-response
application/json
X-Request-Id
X-Request-Id
cabeçalho de solicitação ou um cabeçalho gerado exclusivamente. Use para identificar solicitações entre sistemas e/ou solicitações de suporte.journal
, ok
e/ou requestId
campos.Os códigos de status HTTP são:
-
200 Êxito: quando a solicitação é bem-sucedida. Contém a
journal
O URL que deve ser notificado sobre qualquer resultado do processamento assíncrono acionado via/process
(como tipo de eventosrendition_created
quando bem-sucedido, ourendition_failed
ao falhar).code language-json { "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 Não autorizado: ocorre quando a solicitação não tem um válido autenticação. Um exemplo pode ser um token de acesso inválido ou uma chave de API inválida.
-
403 Proibido: ocorre quando a solicitação não tem um válido autorização. Um exemplo pode ser um token de acesso válido, mas o projeto do Adobe Developer Console (conta técnica) não é assinado por todos os serviços necessários.
-
429 Muitas solicitações: ocorre quando o sistema é sobrecarregado por esse cliente ou por outra razão. Os clientes devem tentar novamente com um retrocesso exponencial. O corpo está vazio.
-
Erro 4xx: quando ocorria qualquer outro erro de cliente e o registro falhava. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Erro 5xx: ocorre quando ocorreu qualquer outro erro no lado do servidor e o registro falhou. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
Cancelar registro da solicitação unregister-request
Essa chamada de API cancela o registro de um Asset Compute cliente. Depois disso, não será mais possível chamar /process
. O uso da chamada de API para um cliente não registrado ou para um cliente a ser registrado retorna um 404
erro.
POST
/unregister
Authorization
x-request-id
Cancelar registro da resposta unregister-response
application/json
X-Request-Id
X-Request-Id
cabeçalho de solicitação ou um cabeçalho gerado exclusivamente. Use para identificar solicitações entre sistemas e/ou solicitações de suporte.ok
e requestId
campos.Os códigos de status são:
-
200 Êxito: ocorre quando o registro e o journal são encontrados e removidos.
code language-json { "ok": true, "requestId": "1234567890" }
-
401 Não autorizado: ocorre quando a solicitação não tem um válido autenticação. Um exemplo pode ser um token de acesso inválido ou uma chave de API inválida.
-
403 Proibido: ocorre quando a solicitação não tem um válido autorização. Um exemplo pode ser um token de acesso válido, mas o projeto do Adobe Developer Console (conta técnica) não é assinado por todos os serviços necessários.
-
404 Não encontrado: ocorre quando não há registro atual para as credenciais fornecidas.
code language-json { "ok": true, "requestId": "1234567890" }
-
429 Muitas solicitações: ocorre quando o sistema está sobrecarregado. Os clientes devem tentar novamente com um retrocesso exponencial. O corpo está vazio.
-
Erro 4xx: ocorre quando ocorreu qualquer outro erro de cliente e o cancelamento de registro falhou. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Erro 5xx: ocorre quando ocorreu qualquer outro erro no lado do servidor e o registro falhou. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
Processar solicitação process-request
A variável process
A operação envia um trabalho que transforma um ativo de origem em várias representações, com base nas instruções na solicitação. Notificações sobre conclusão com êxito (tipo de evento) rendition_created
) ou qualquer erro (tipo de evento rendition_failed
) são enviados para um Diário de eventos que deve ser recuperado usando /register uma vez antes de efetuar qualquer número de /process
solicitações. Solicitações formadas incorretamente falham imediatamente com um código de erro 400.
Os binários são referenciados usando URLs, como URLs pré-assinados do Amazon AWS S3 ou URLs SAS do Armazenamento Azure Blob, para ler o source
ativo (GET
URLs) e gravação das representações (PUT
URLs) O cliente é responsável por gerar esses URLs pré-assinados.
POST
/process
application/json
Authorization
x-request-id
Processar solicitação JSON process-request-json
O corpo da solicitação de /process
é um objeto JSON com este esquema de alto nível:
{
"source": "",
"renditions" : []
}
Os campos disponíveis são:
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" }]
A variável source
pode ser um <string>
que é visto como um URL ou pode ser um <object>
com um campo adicional. As seguintes variantes são semelhantes:
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Campos do objeto de origem source-object-fields
url
string
"http://example.com/image.jpg"
name
string
content-disposition
cabeçalho do recurso binário. O padrão é "file"."image.jpg"
size
number
content-length
cabeçalho do recurso binário.10234
mimetype
string
content-type
cabeçalho do recurso binário."image/jpeg"
Um process
exemplo de solicitação 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"
}]
}
Processar resposta process-response
A variável /process
A solicitação do retorna imediatamente com êxito ou falha com base na validação básica da solicitação. O processamento de ativos real ocorre de forma assíncrona.
application/json
X-Request-Id
X-Request-Id
cabeçalho de solicitação ou um cabeçalho gerado exclusivamente. Use para identificar solicitações entre sistemas e/ou solicitações de suporte.ok
e requestId
campos.Códigos de status:
-
200 Êxito: se a solicitação foi enviada com êxito. A resposta JSON inclui
"ok": true
:code language-json { "ok": true, "requestId": "1234567890" }
-
400 Solicitação inválida: se a solicitação estiver formada incorretamente, como campos obrigatórios ausentes no JSON da solicitação. A resposta JSON inclui
"ok": false
:code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 Não autorizado: quando a solicitação não tiver uma conta válida autenticação. Um exemplo pode ser um token de acesso inválido ou uma chave de API inválida.
-
403 Proibido: quando a solicitação não tiver uma conta válida autorização. Um exemplo pode ser um token de acesso válido, mas o projeto do Adobe Developer Console (conta técnica) não é assinado por todos os serviços necessários.
-
429 Muitas solicitações: quando o sistema é sobrecarregado por esse cliente ou, em geral, Os clientes podem tentar novamente com um retrocesso exponencial. O corpo está vazio.
-
Erro 4xx: quando ocorria qualquer outro erro de cliente. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
-
Erro 5xx: quando havia qualquer outro erro do lado do servidor. Normalmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:
code language-json { "ok": false, "requestId": "1234567890", "message": "error message" }
Provavelmente, a maioria dos clientes está inclinada a repetir exatamente a mesma solicitação com retrocesso exponencial em qualquer erro exceto problemas de configuração como 401 ou 403, ou solicitações inválidas como 400. Além da limitação de taxa regular por meio de respostas 429, uma interrupção ou limitação temporária de serviço pode resultar em erros 5xx. Em seguida, seria aconselhável tentar novamente após um período.
Todas as respostas JSON (se presentes) incluem o requestId
que tem o mesmo valor que a variável X-Request-Id
cabeçalho. É recomendável ler a partir do cabeçalho, pois ele está sempre presente. A variável requestId
também é retornado em todos os eventos relacionados às solicitações de processamento como requestId
. Os clientes não devem fazer qualquer suposição sobre o formato dessa cadeia de caracteres. Ele é um identificador de cadeia de caracteres opaco.
Aceitar o pós-processamento opt-in-to-post-processing
A variável ASSET COMPUTE SDK O oferece suporte a um conjunto de opções básicas de pós-processamento de imagem. Os trabalhadores personalizados podem aceitar explicitamente o pós-processamento definindo o campo postProcess
no objeto de representação para true
.
Os casos de uso compatíveis são:
- Cortar uma representação em um retângulo cujos limites são definidos por crop.w, crop.h, crop.x e crop.y. É definido por
instructions.crop
no objeto de representação. - Redimensionar imagens usando largura, altura ou ambos. É definido por
instructions.width
einstructions.height
no objeto de representação. Para redimensionar usando apenas largura ou altura, defina apenas um valor. O serviço de computação conserva a taxa de proporção. - Defina a qualidade de uma imagem JPEG. É definido por
instructions.quality
no objeto de representação. A melhor qualidade é indicada por100
e valores menores indicam qualidade reduzida. - Criar imagens entrelaçadas. É definido por
instructions.interlace
no objeto de representação. - Defina DPI para ajustar o tamanho renderizado para fins de publicação em desktop, ajustando a escala aplicada aos pixels. É definido por
instructions.dpi
no objeto de representação para alterar a resolução da dpi. No entanto, para redimensionar a imagem para que fique com o mesmo tamanho em uma resolução diferente, use oconvertToDpi
instruções. - Redimensionar a imagem de forma que sua largura ou altura renderizada permaneça a mesma que a original na resolução de destino especificada (DPI). É definido por
instructions.convertToDpi
no objeto de representação.
Inserir marca d'água em ativos add-watermark
A variável ASSET COMPUTE SDK O suporta a adição de uma marca d'água aos arquivos de imagem PNG, JPEG, TIFF e GIF. A marca d'água é adicionada seguindo as instruções de representação na watermark
objeto na representação.
A marca d'água é feita durante o pós-processamento da representação. Para criar uma marca d'água nos ativos, o trabalhador personalizado opta pelo pós-processamento definindo o campo postProcess
no objeto de representação para true
. Se o trabalhador não aceitar, a marca d'água não será aplicada, mesmo que o objeto de marca d'água esteja definido no objeto de representação na solicitação.
Instruções de representação rendition-instructions
Estas são as opções disponíveis para o renditions
matriz em /process.
Campos comuns common-fields
fmt
string
text
para extração de texto e xmp
para extrair metadados de XMP como xml. Consulte formatos compatíveispng
worker
string
https://
URL. Se esse campo estiver presente, a representação será criada por um aplicativo personalizado. Qualquer outro campo de representação definido é usado no aplicativo personalizado."https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
Informações de upload de URL pré-assinado de várias partes para a representação gerada. Este é para Upload binário direto do AEM/Oak com este comportamento de upload de várias partes.
Campos:
urls
: matriz de cadeias de caracteres, uma para cada URL de parte pré-assinadominPartSize
: o tamanho mínimo a ser usado para uma parte = urlmaxPartSize
: o tamanho máximo a ser usado para uma parte = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
Campos específicos da representação rendition-specific-fields
Para obter uma lista de formatos de arquivo compatíveis no momento, consulte formatos de arquivo compatíveis.
*
*
embedBinaryLimit
number
em bytesembedBinaryLimit
limite, ele deve ser colocado em um local no armazenamento na nuvem e não está incorporado no evento.3276
width
number
200
height
number
200
A proporção será sempre mantida se:
- Ambos
width
eheight
forem especificadas, a imagem se ajustará no tamanho, mantendo a proporção - Somente
width
ou somenteheight
for especificada, a imagem resultante usará a dimensão correspondente, mantendo a proporção - Se nenhuma delas
width
nemheight
for especificado, o tamanho do pixel da imagem original será usado. Depende do tipo de origem. Para alguns formatos, como arquivos PDF, um tamanho padrão é usado. Pode haver um limite de tamanho máximo.
quality
number
1
para 100
. Aplicável somente para representações de imagem.90
xmp
string
interlace
bool
true
. Não tem efeito em outros formatos de arquivo.jpegSize
number
quality
configuração. Não tem efeito em outros formatos.dpi
number
ou object
96
ou { xdpi: 96, ydpi: 96 }
convertToDpi
number
ou object
96
ou { xdpi: 96, ydpi: 96 }
files
array
Lista de arquivos a serem incluídos no arquivo ZIP (fmt=zip
). Cada entrada pode ser uma string de URL ou um objeto com os campos:
url
: URL para baixar o arquivopath
: armazene o arquivo nesse caminho no ZIP
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
). Por padrão, vários arquivos armazenados no mesmo caminho no ZIP geram um erro. Configuração duplicate
para ignore
resulta no armazenamento somente do primeiro ativo e o restante é ignorado.ignore
Campos específicos de marca d'água watermark-specific-fields
O formato PNG é usado como marca d'água.
scale
number
0.0
e 1.0
. 1.0
significa que a marca d'água tem sua escala original (1:1) e os valores mais baixos reduzem o tamanho da marca d'água.0.5
significa metade do tamanho original.image
url
Eventos assíncronos asynchronous-events
Quando o processamento de uma representação for concluído ou quando ocorrer um erro, um evento será enviado para um Adobe I/O Diário de eventos. Os clientes devem escutar o URL do diário fornecido por meio de /register. A resposta do diário inclui uma event
matriz que consiste em um objeto para cada evento, do qual a variável event
inclui a carga útil real do evento.
A variável Adobe I/O Tipo de evento para todos os eventos do Asset Compute Service é asset_compute
. O journal é automaticamente inscrito somente neste tipo de evento e não há mais necessidade de filtrar com base no Adobe I/O Tipo de evento. Os tipos de evento específicos do serviço estão disponíveis no type
propriedade do evento.
Tipos de evento event-types
rendition_created
rendition_failed
Atributos do evento event-attributes
date
string
*
requestId
string
*
/process
, igual a X-Request-Id
cabeçalho.source
object
*
source
do /process
solicitação.userData
object
*
userData
da representação da /process
solicitação se definida.rendition
object
rendition_*
/process
.errorMessage
string
rendition_failed
Metadados metadata
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
Motivos de erro error-reasons
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
. O tamanho real da representação está disponível como metadados no repo:size
e podem ser usados pelo cliente para processar novamente essa representação com o número correto de URLs pré-assinados.GenericError