HTTP File Trigger - Uploads

Descubra mais sobre o HTTP File Trigger e saiba como utilizá-lo para fazer uploads na Digibee Integration Platform.

O HTTP File Trigger envia arquivos grandes (com tamanho superior a 5 MB) para pipelines de forma robusta e eficiente, usando HTTP.

Paramêtros

Dê uma olhada nas opções de configuração do componente. Parâmetros suportados por expressões Double Braces estão marcados com (DB).

ParâmetroDescriçãoValor padrãoTipo de dado

Methods

Define os métodos aceitos pelo pipeline (GET, PUT, POST, PATCH e DELETE).

POST, PUT, GET, PATCH e DELETE

String

Response Headers

Headers a serem retornados pelo endpoint quando o processamento no pipeline terminar.

N/A

Key-Value Pairs

Add Cross-Origin Resource Sharing (CORS) - CORS Headers

Adicione os CORS headers a serem retornados pelo endpoint quando o processamento no pipeline terminar.

N/A

Key-Value Pairs

Form Data Uploads

Habilita/desabilita o recebimento do upload de form data (multi-part form data).

True

Booleano

Body Uploads

Habilita/desabilita o recebimento do upload de bodies.

True

Booleano

Body Upload Content Types

Define os content types permitidos pelo pipeline para o upload de bodies.

application/pdf, application/jpeg

String

Response Content Types

Define os content types de resposta permitidos para o pipeline - ao configurar essa resposta, você determina o formato de resposta.

text/xml, application/xml

String

Maximum Timeout

Tempo máximo (em milissegundos) para o pipeline processar informação antes de retornar uma resposta.

30000

Inteiro

Maximum Request Size

Define o tamanho máximo do arquivo na solicitação de upload (em MB).

100

Inteiro

External API

Se ativada, a opção pública a API em um gateway externo.

True

Booleano

Internal API

Se ativada, a opção pública a API em um gateway interno.

False

Booleano

mTLS enabled API

Se a opção estiver ativada, a API é publicada em um gateway dedicado a APIs com mTLS ativo por padrão.

False

Booleano

API Key

Se ativada, a opção vai solicitar a chave para consumo do API.

False

Booleano

Token JWT

Se ativada, a opção vai solicitar o token para consumo do API.

False

Booleano

Basic Auth (Fase Beta)

Se a opção estiver ativada, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição.

False

Booleano

Additional API Routes

Se ativada, a opção permite que você adicione novas rotas.

False

Booleano

Remove Digibee Prefix from Route

Esta opção estará disponível somente quando os parâmetros External API e Internal API estiverem desabilitados, e os parâmetros mTLS enabled API e Additional API Routes estiverem habilitados. Defina esta opção para remover o prefixo de rota padrão Digibee "/pipeline/{realm}/v{n}" da rota do pipeline. Saiba mais sobre o parâmetro Remove Digibee Prefix from Route na seção abaixo.

False

Booleano

API Routes

Rotas customizáveis.

N/A

String

Rate Limit

Se a opção estiver ativada, uma configuração de rate limiting será aplicada no API Gateway. Esta opção estará disponível somente se API Key ou Basic Auth estiverem ativados. Veja mais sobre esse parâmetro na seção abaixo.

False

Booleano

Limit by

Define a entidade na qual os limites serão aplicados. Opções: API.

API

String

Aggregate by

Define a entidade agregadora dos limites. Opções: Consumer e Credential (API Key, Basic Auth).

Consumer

String

Options

Define o limite de requisições que podem ser feitas dentro de um período de tempo.

N/A

Opções para limit e interval

Interval

Define o intervalo de tempo para o limite de requisições. Opções: second, minute, hour, day e month.

second

String

Limit

Define o número máximo de requisições que os usuários podem fazer no intervalo de tempo especificado.

N/A

Inteiro

Allow Redelivery Of Messages

Se ativada, a opção permite que as mensagens sejam entregues novamente caso o Pipeline Engine falhe.

False

Booleano

Existe um parâmetro de configuração global que obriga todos os pipelines a serem publicados com ao menos a opção API Key ou Basic Auth habilitada.

Informações adicionais sobre parâmetros

Add Cross-Origin Resource Sharing (CORS) - CORS Headers (DB)

Utilizamos vírgula para informar múltiplos valores em um header, mas não adicionamos espaço antes ou após a vírgula. Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.

mTLS enabled API

Este parâmetro não suporta API Key, JWT ou Basic Auth. Para utilizá-lo no seu realm, é necessário fazer uma solicitação via chat e assim enviaremos as informações necessárias para instalação deste serviço.

Remove Digibee Prefix from Route

Como explicado anteriormente, esta opção é recomendada para remover o prefixo de rota padrão Digibee da rota do pipeline.

Digamos que você tenha criado um pipeline e definido o trigger da seguinte forma:

Com as configurações aplicadas e o pipeline implantado, você terá uma nova URL:

https://test.godigibee.io/products

Ao remover o prefixo padrão e definir a rota do pipeline pelo parâmetro Additional API Routes, tenha cuidado para não definir uma rota de pipeline existente que esteja em uso por outros pipelines. Caso você tenha mais do que uma versão principal do pipeline, também é importante ter em mente que o versionamento da rota do pipeline deve ser feito pelo usuário devido à ausência de um parâmetro para versionamento da rota. Por exemplo: /pipeline/realm/v1/.

Rate Limit

Ao criarmos APIs, geralmente queremos limitar o número de requisições da API que usuários podem fazer em um dado intervalo de tempo.

Esta ação pode ser executada ativando a opção Rate Limit e aplicando as seguintes configurações:

Se a API possui rotas adicionais, o limite é compartilhado entre todas as rotas. Para aplicar as configurações de rate limit, a API precisa ser configurada com uma API Key ou Basic Auth para que o parâmetro Aggregate by possa ser usado por grupos de credenciais se a opção Consumer estiver selecionada, ou por credenciais individuais se a opção Credential (API Key, Basic Auth) estiver selecionada.

Se vários parâmetros Interval estiverem configurados com valores repetidos, apenas um desses valores é considerado. Também é necessário que um valor maior que zero seja informado para o parâmetro Limit.

Se as opções de rate limiting não forem definidas corretamente, elas serão ignoradas e um warning log será emitido. Você pode visualizar esse log na página de Pipeline Logs.

HTTP File Trigger em ação

Cenário 1: POST de um arquivo com content type multipart/form-data

Digamos que você queira enviar um arquivo com mais de 5MB. Você pode chamar um endpoint de pipeline configurado com HTTP Trigger via POST com o content type multipart/form-data para que esse arquivo fique disponível para ser trabalhado pelo pipeline.

Veja como fazer isso:

  1. Crie um pipeline e configure seu trigger como HTTP-File, habilitando a opção Form Data Uploads.

  2. Implante o pipeline.

  3. Crie um consumer e o configure de modo que tenha acesso ao pipeline.

  4. Chame o pipeline através deste curl:

curl -d “@file_name” https://godigibee.io/pipeline/realm_name/v1/http-file-upload  -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token'
  • file_name: se refere a um arquivo local.

  • realm_name: se refere ao realm onde o pipeline se encontra.

  • generated_token: se refere à chave de API gerada pelo consumer recém-criado.

O pipeline receberá um array files[] contendo:

  • fileName

  • param

  • contentType

Dessa maneira, o arquivo pode ser referenciado e acessado a partir do pipeline:

{
  "body": null,
  "form": {},
  "headers": {
  ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {      
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"    
    }  
  ]
}

Cenário 2: POST de múltiplos arquivos com content type multipart/form-data

Digamos que você tenha vários arquivos com mais de 5MB. Você pode chamar um endpoint de pipeline configurado com HTTP Trigger via POST com o content type multipart/form-data para que esses arquivos fiquem disponíveis para serem trabalhados pelo pipeline.

Para viabilizar isso, basta seguir estes passos:

  1. Crie um pipeline e configure seu trigger como HTTP-File, habilitando a opção Form Data Uploads.

  2. Implante o pipeline.

  3. Crie um consumer e o configure de modo que tenha acesso ao pipeline.

  4. Chame o pipeline através deste curl:

curl -F dgbfile1=@file_name1 -F dgbfile2=@file_name2 https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
  • file_name1: se refere a um arquivo local.

  • file_name2: se refere a um arquivo local.

  • realm_name: se refere ao realm onde o pipeline se encontra.

  • generated_token: se refere à chave de API gerada pelo consumer recém-criado.

O pipeline receberá um array files[] contendo:

  • fileName

  • originalFileName

  • param

  • charset

  • contentLength

  • contentType

Dessa maneira, os arquivos podem ser referenciados e acessados a partir do pipeline:

{
  "body": "",
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "multipart/form-data; boundary=------------------------b3c985803b952f2c",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "96f3ecb2-1c72-4980-9f01-6f44cafc719f",
      "originalFileName": "file1",
      "param": "dgbfile1",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    },
    {
      "fileName": "58fb844f-a1d1-4788-b9b4-30df4b69165e",
      "originalFileName": "file2",
      "param": "dgbfile2",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    }
  ]
}

Cenário 3: POST com qualquer content type e body com mais de 5 MB

Digamos que você tenha vários arquivos com mais de 5MB. Você pode chamar um endpoint de pipeline configurado com HTTP Trigger via POST com qualquer content type para que esses arquivos fiquem disponíveis para serem trabalhados pelo pipeline.

Tudo o que você tem que fazer é:

  1. Criar um pipeline e configure seu trigger como HTTP-File, habilitando a opção Body Uploads.

  2. Implantar o pipeline.

  3. Criar um consumer e o configure de modo que tenha acesso ao pipeline.

  4. Chamar o pipeline através deste curl:

curl -d '@file_name1' https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
  • file_name: se refere a um arquivo local.

  • realm_name: se refere ao realm onde o pipeline se encontra.

  • generated_token: se refere à chave de API gerada pelo consumer recém-criado.

O pipeline receberá um array files[] contendo:

  • fileName

  • param

  • charset

  • contentType

Dessa maneira, os arquivos podem ser referenciados e acessados a partir do pipeline:

{
  "body": null,
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"
    }
  ]
}

Resposta do HTTP File Trigger

É simples definir o formato da resposta do pipeline. Adicione um Transformer ao final do pipeline e defina a resposta:

{  
    "body": "<xml>Output 1</xml>",  
    "code": 200,  
    "Content-Type": "application/xml"
}

Outra solução é indicada em situações onde há uma limitação de tamanho de resposta para payloads maiores que 5 MB. Nesse caso, é recomendável que a resposta do pipeline seja um arquivo e não um payload. Isso pode ser feito usando o componente File Writer para gerar o arquivo e referenciá-lo na resposta do pipeline através da propriedade "file" ao invés da propriedade "body":

{
"file": {{ message.fileName }},
"code": 200,
"Content-Type": "application/json"
}

Content-Type precisa ser um dos valores definidos em Response Content Types.

Leia o artigo HTTP File Trigger - Downloads para saber como se certificar de que a saída do pipeline seja um arquivo.

Atualizado