Asset Compute Service API HTTP

O uso da API é limitado a propósitos de desenvolvimento. A API é fornecida como um contexto ao desenvolver aplicativos personalizados. Adobe Experience Manager O as a Cloud Service 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.

OBSERVAÇÃO

Asset Compute Service está disponível somente para uso com Experience Manager as a Cloud Service.

Qualquer cliente da API HTTP Asset Compute Service deve seguir esse fluxo de alto nível:

  1. Um cliente é provisionado como projeto 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.

  2. Um cliente gera um token de acesso para a conta técnica usando a Autenticação JWT (Conta de Serviço).

  3. Um cliente chama /register apenas uma vez para recuperar o URL do diário.

  4. Um cliente chama /process para cada ativo para o qual deseja gerar representações. A chamada é assíncrona.

  5. Um cliente pesquisa regularmente o diário para receber eventos. Ele recebe eventos para cada representação solicitada quando a representação é processada com êxito (tipo de evento rendition_created ) ou se há um erro (tipo de evento rendition_failed ).

O módulo @adobe/asset-compute-client facilita o uso da API no código Node.js.

Autenticação e autorização

Todas as APIs exigem autenticação de token de acesso. As solicitações devem definir os seguintes cabeçalhos:

  1. Authorization cabeçalho com token portador, que é o token de conta técnica, recebido por meio do JWT exchange do Adobe Developer Console. Os escopos estão documentados abaixo.
  1. x-gw-ims-org-id com a ID da organização IMS.

  2. x-api-key com a ID do cliente do Adobe Developers Console projeto.

Escopos

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

Isso requer que o projeto Adobe Developer Console seja inscrito nos serviços Asset Compute, I/O Events e I/O Management API. O detalhamento de escopos individuais é:

  • Básico

    • escopos: openid,AdobeID
  • asset compute

    • metascópio: asset_compute_meta
    • escopos: asset_compute,read_organizations
  • Adobe I/O Eventos

    • metascópio: event_receiver_api
    • escopos: event_receiver,event_receiver_api
  • Adobe I/O API de gerenciamento

    • metascópio: ent_adobeio_sdk
    • escopos: adobeio_api,additional_info.roles,additional_info.projectedProductContext

Registro

Cada cliente do Asset Compute service - um projeto exclusivo Adobe Developer Console 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 o registro.

Solicitação de registro

Essa chamada de API define um cliente 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.

Parâmetro Valor
Método POST
Caminho /register
Cabeçalho Authorization Todos os cabeçalhos relacionados à autorização.
Cabeçalho x-request-id Opcional, pode ser definido pelos clientes para um identificador completo exclusivo das solicitações de processamento em todos os sistemas.
Corpo da solicitação Deve estar vazio.

Registrar resposta

Parâmetro Valor
Tipo MIME application/json
Cabeçalho X-Request-Id O mesmo que o cabeçalho da solicitação X-Request-Id ou um único gerado. Use para identificar solicitações em sistemas e/ou solicitações de suporte.
Corpo de resposta Um objeto JSON com campos journal, ok e/ou requestId.

Os códigos do status HTTP são:

  • 200 Sucesso: Quando a solicitação é bem-sucedida. Ele contém o URL journal que é notificado sobre qualquer resultado do processamento assíncrono acionado via /process (como eventos, digite rendition_created quando bem-sucedido ou rendition_failed quando falhar).

    {
        "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 autenticação válida. 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 autorização válida. Um exemplo pode ser um token de acesso válido, mas o projeto do Console do desenvolvedor do Adobe (conta técnica) não está inscrito em todos os serviços necessários.

  • 429 Demasiados pedidos: ocorre quando o sistema é sobrecarregado por este cliente ou de outra forma. Os clientes devem tentar novamente com um backoff exponencial. O corpo está vazio.

  • Erro 4xx: Quando havia outro erro de cliente e o registro falhou. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    
  • Erro 5xx: ocorre quando houve qualquer outro erro do lado do servidor e o registro falhou. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    

Solicitação de cancelamento de registro

Essa chamada de API cancela o registro de um cliente Asset Compute. Depois disso, não é mais possível chamar /process. Usar a chamada da API para um cliente não registrado ou um cliente ainda não registrado retorna um erro 404.

Parâmetro Valor
Método POST
Caminho /unregister
Cabeçalho Authorization Todos os cabeçalhos relacionados à autorização.
Cabeçalho x-request-id Opcional, pode ser definido pelos clientes para um identificador completo exclusivo das solicitações de processamento em todos os sistemas.
Corpo da solicitação Vazio.

Cancelar registro da resposta

Parâmetro Valor
Tipo MIME application/json
Cabeçalho X-Request-Id O mesmo que o cabeçalho da solicitação X-Request-Id ou um único gerado. Use para identificar solicitações em sistemas e/ou solicitações de suporte.
Corpo de resposta Um objeto JSON com os campos ok e requestId.

Os códigos de status são:

  • 200 Sucesso: ocorre quando o registro e o diário são encontrados e removidos.

    {
        "ok": true,
        "requestId": "1234567890"
    }
    
  • 401 Não Autorizado: ocorre quando a solicitação não tem autenticação válida. 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 autorização válida. Um exemplo pode ser um token de acesso válido, mas o projeto do Console do desenvolvedor do Adobe (conta técnica) não está inscrito em todos os serviços necessários.

  • 404 Não encontrado: ocorre quando não há registro atual para as credenciais fornecidas.

    {
        "ok": true,
        "requestId": "1234567890"
    }
    
  • 429 Demasiados pedidos: ocorre quando o sistema é sobrecarregado. Os clientes devem tentar novamente com um backoff exponencial. O corpo está vazio.

  • Erro 4xx: ocorre quando houve outro erro de cliente e o cancelamento de registro falhou. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    
  • Erro 5xx: ocorre quando houve qualquer outro erro do lado do servidor e o registro falhou. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    

Solicitação de processo

A operação process envia uma tarefa que transforma um ativo de origem em várias representações, com base nas instruções na solicitação. As notificações sobre conclusão com êxito (tipo de evento rendition_created) ou quaisquer erros (tipo de evento rendition_failed) são enviadas para um diário de Eventos que deve ser recuperado usando /register uma vez antes de fazer qualquer número de solicitações /process. As 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 ativo source (GET URLs) e gravar as representações (PUT URLs). O cliente é responsável pela geração desses URLs pré-assinados.

Parâmetro Valor
Método POST
Caminho /process
Tipo MIME application/json
Cabeçalho Authorization Todos os cabeçalhos relacionados à autorização.
Cabeçalho x-request-id Opcional, pode ser definido pelos clientes para um identificador completo exclusivo das solicitações de processamento em todos os sistemas.
Corpo da solicitação Deve estar no formato JSON de solicitação de processo, conforme descrito abaixo. Ele fornece instruções sobre qual ativo processar e quais execuções gerar.

JSON de solicitação de processo

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:

Nome Tipo Descrição Exemplo
source string URL do ativo de origem a ser processado. Opcional com base no formato de representação solicitado (por exemplo, fmt=zip). "http://example.com/image.jpg"
source object Descrição do ativo de origem a ser processado. Consulte a descrição de Campos de objeto de origem abaixo. Opcional com base no formato de representação solicitado (por exemplo, fmt=zip). {"url": "http://example.com/image.jpg", "mimeType": "image/jpeg" }
renditions array Representações a serem geradas a partir do arquivo de origem. Cada objeto de representação suporta instrução de representação. Obrigatório. [{ "target": "https://....", "fmt": "png" }]

O source pode ser um <string> que é visto como um URL ou 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 de objeto de origem

Nome Tipo Descrição Exemplo
url string URL do ativo de origem a ser processado. Obrigatório. "http://example.com/image.jpg"
name string Nome do arquivo de ativo de origem. A extensão de arquivo no nome pode ser usada se nenhum tipo MIME puder ser detectado. Tem precedência sobre o nome do arquivo no caminho do URL ou no nome do arquivo no cabeçalho content-disposition do recurso binário. O padrão é "arquivo". "image.jpg"
size number Tamanho do arquivo de ativo de origem em bytes. Tem precedência sobre o cabeçalho content-length do recurso binário. 10234
mimetype string Tipo MIME do arquivo de ativo de origem. Tem precedência sobre o cabeçalho content-type do recurso binário. "image/jpeg"

Um exemplo completo de solicitação 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"
    }]
}

Resposta do processo

A solicitação /process retorna imediatamente com um sucesso ou uma falha com base na validação básica da solicitação. O processamento de ativos reais ocorre de forma assíncrona.

Parâmetro Valor
Tipo MIME application/json
Cabeçalho X-Request-Id O mesmo que o cabeçalho da solicitação X-Request-Id ou um único gerado. Use para identificar solicitações em sistemas e/ou solicitações de suporte.
Corpo de resposta Um objeto JSON com os campos ok e requestId.

Códigos de status:

  • 200 Sucesso: Se a solicitação foi enviada com êxito. O JSON de resposta inclui "ok": true:

    {
        "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. O JSON de resposta inclui "ok": false:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    
  • 401 Não Autorizado: Quando a solicitação não tem autenticação válida. 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 tem autorização válida. Um exemplo pode ser um token de acesso válido, mas o projeto do Console do desenvolvedor do Adobe (conta técnica) não está inscrito em todos os serviços necessários.

  • 429 Demasiados pedidos: Quando o sistema é sobrecarregado por este cliente ou em geral. Os clientes podem tentar novamente com um backoff exponencial. O corpo está vazio.

  • Erro 4xx: Quando havia outro erro de cliente. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    
  • Erro 5xx: Quando havia outro erro no lado do servidor. Geralmente, uma resposta JSON como essa é retornada, embora isso não seja garantido para todos os erros:

    {
        "ok": false,
        "requestId": "1234567890",
        "message": "error message"
    }
    

A maioria dos clientes provavelmente tem tendência para repetir exatamente a mesma solicitação com backoff 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 regular da taxa por meio de respostas 429, uma interrupção ou limitação temporária do serviço pode resultar em erros 5xx. Seria então aconselhável tentar de novo após um período de tempo.

Todas as respostas JSON (se presentes) incluem o requestId que é o mesmo valor do cabeçalho X-Request-Id. É recomendável ler a partir do cabeçalho, já que ele está sempre presente. O requestId também é retornado em todos os eventos relacionados ao processamento de solicitações como requestId. Os clientes não devem assumir nenhuma suposição sobre o formato dessa string, ele é um identificador de string opaco.

Aceitar pós-processamento

O SDK do Asset compute suporta 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:

  • Recorte uma representação em um retângulo cujos limites são definidos por cortar.w, cortar.h, cortar.x e cortar.y. É definido por instructions.crop no objeto de representação.
  • Redimensione as imagens usando largura, altura ou ambas. Ela é definida por instructions.width e instructions.height no objeto de representação. Para redimensionar usando somente 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 por 100 e valores menores indicam qualidade reduzida.
  • Crie imagens entrelaçadas. É definido por instructions.interlace no objeto de representação.
  • Defina o DPI para ajustar o tamanho renderizado para fins de publicação de 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 de modo que ela tenha o mesmo tamanho em uma resolução diferente, use as instruções convertToDpi.
  • Redimensione a imagem de forma que sua largura ou altura renderizada permaneça a mesma do original na DPI (resolução de destino especificada). É definido por instructions.convertToDpi no objeto de representação.

Ativos de marca d'água

O SDK do Asset compute oferece suporte à 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 no objeto watermark na representação.

A marca d'água é feita durante o pós-processamento da representação. Para criar ativos de marca d'água, o trabalhador personalizado opta por 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 da marca d'água esteja definido no objeto de representação na solicitação.

Instruções de representação

Essas são as opções disponíveis para a matriz renditions em /process.

Campos comuns

Nome Tipo Descrição Exemplo
fmt string O formato de destino de representações também pode ser text para extração de texto e xmp para extração de metadados de XMP como xml. Consulte formatos compatíveis png
worker string URL de um aplicativo personalizado. Deve ser um URL https://. 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 URL para o qual a representação gerada deve ser carregada usando HTTP PUT. http://w.com/img.jpg
target object Multiplica informações de upload de URL pré-assinado para a representação gerada. Isso é para AEM/Oak Direct Binary Upload com este comportamento de upload multiparte.
Fields:
  • urls: matriz de strings, uma para cada URL de parte pré-assinada
  • minPartSize: o tamanho mínimo a ser usado para uma parte = url
  • maxPartSize: o tamanho máximo a ser usado para uma parte = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData object Espaço reservado opcional controlado pelo cliente e passado como está para eventos de representação. Permite que os clientes adicionem informações personalizadas para identificar eventos de representação. Não deve ser modificado ou confiável em aplicativos personalizados, pois os clientes podem alterá-lo a qualquer momento. { ... }

Campos específicos da representação

Para obter uma lista de formatos de arquivo compatíveis no momento, consulte formatos de arquivo compatíveis.

Nome Tipo Descrição Exemplo
* * Campos avançados e personalizados podem ser adicionados e um aplicativo personalizado entende.
embedBinaryLimit number em bytes Se esse valor for definido e o tamanho do arquivo da representação for menor que esse valor, a representação será incorporada no evento enviado após a conclusão da geração da representação. O tamanho máximo permitido para incorporação é 32 KB (32 x 1024 bytes). Se uma representação tiver um tamanho maior que o limite embedBinaryLimit, ela será colocada em um local no armazenamento da nuvem e não será incorporada ao evento. 3276
width number Largura em pixels. somente para representações de imagem. 200
height number Altura em pixels. somente para representações de imagem. 200
A taxa de proporção é sempre mantida se:
  • width e height são especificadas, então a imagem se ajusta ao tamanho, mantendo a proporção do aspecto
  • Somente width ou apenas height é especificado, a imagem resultante usa a dimensão correspondente enquanto mantém a proporção do aspecto
  • Se width ou height não for especificado, o tamanho do pixel da imagem original será usado. Depende do tipo de origem. Para alguns formatos, como arquivos PDF, é usado um tamanho padrão. Pode haver um limite máximo de tamanho.
quality number Especifique a qualidade do jpeg no intervalo de 1 a 100. Aplicável somente para representações de imagem. 90
xmp string Usado apenas XMP write-back de metadados, é XMP codificado em base64 para gravar de volta na representação especificada.
interlace bool Crie PNG ou GIF entrelaçado ou JPEG progressivo ao configurá-lo para true. Não tem efeito sobre outros formatos de arquivo.
jpegSize number Tamanho aproximado do arquivo JPEG em bytes. Substitui qualquer configuração quality. Não afeta outros formatos.
dpi number ou object Defina x e y DPI. Para simplificar, também pode ser definido para um único número que é usado para x e y. Não tem efeito na própria imagem. 96 ou { xdpi: 96, ydpi: 96 }
convertToDpi number ou object x e y DPI refazem valores, mantendo o tamanho físico. Para simplificar, também pode ser definido para um único número que é usado para x e y. 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 arquivo
  • path: Armazenar arquivo sob este caminho no ZIP
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate string Manuseio duplicado de arquivos ZIP (fmt=zip). Por padrão, vários arquivos armazenados no mesmo caminho no ZIP gera um erro. Definir duplicate como ignore resulta somente no primeiro ativo a ser armazenado e no restante a ser ignorado. ignore
watermark object Contém instruções sobre a marca d'água.

Campos específicos de marca d'água

O formato PNG é usado como uma marca d'água.

Nome Tipo Descrição Exemplo
scale number Escala da marca d'água, entre 0.0 e 1.0. 1.0 significa que a marca de água tem a escala original (1:1) e os valores inferiores reduzem o tamanho da marca de água. Um valor de 0.5 significa metade do tamanho original.
image url URL do arquivo PNG a ser usado para marca d'água.

Eventos assíncronos

Quando o processamento de uma representação é concluído ou quando um erro ocorre, um evento é enviado para um Adobe I/O Events Journal. Os clientes devem ouvir o URL do diário fornecido por meio de /register. A resposta do diário inclui uma matriz event que consiste em um objeto para cada evento, do qual o campo event inclui a carga útil real do evento.

O tipo de Evento Adobe I/O para todos os eventos do Asset Compute Service é asset_compute. O diário é automaticamente inscrito somente nesse tipo de evento e não há mais nenhum requisito para filtrar com base no tipo de Evento Adobe I/O. Os tipos de evento específicos do serviço estão disponíveis na propriedade type do evento.

Tipos de evento

Evento Descrição
rendition_created Enviado para cada renderização processada e carregada com êxito.
rendition_failed Enviado para cada representação que não processou ou fez upload.

Atributos do evento

Atributo Tipo Evento Descrição
date string * Carimbo de data e hora quando o evento foi enviado no formato simplificado ISO-8601, conforme definido pelo JavaScript Date.toISOString().
requestId string * O ID da solicitação original para /process, igual ao cabeçalho X-Request-Id.
source object * O source da solicitação /process.
userData object * O userData da representação da solicitação /process, se estiver definido.
rendition object rendition_* O objeto de representação correspondente transmitido em /process.
metadata object rendition_created As propriedades metadata da representação.
errorReason string rendition_failed Falha de representação reason se houver.
errorMessage string rendition_failed Texto que fornece mais detalhes sobre a falha de representação, se houver.

Metadados

Propriedade Descrição
repo:size O tamanho da representação em bytes.
repo:sha1 O resumo sha1 da representação.
dc:format O tipo MIME da representação.
repo:encoding A codificação charset da representação, caso seja um formato baseado em texto.
tiff:ImageWidth A largura da representação em pixels. Apresentado apenas para representações de imagem.
tiff:ImageLength O comprimento da representação em pixels. Apresentado apenas para representações de imagem.

Motivos de erro

Motivo Descrição
RenditionFormatUnsupported Não há suporte para o formato de representação solicitado para a fonte em questão.
SourceUnsupported A origem específica não é suportada mesmo que o tipo seja suportado.
SourceCorrupt Os dados de origem estão corrompidos. Inclui arquivos vazios.
RenditionTooLarge A representação não pôde ser carregada usando os URLs pré-assinados fornecidos em target. O tamanho da representação real está disponível como metadados em repo:size e pode ser usado pelo cliente para reprocessar essa representação com o número correto de URLs pré-assinados.
GenericError Qualquer outro erro inesperado.

Nesta página