HTTP File Trigger (Upload and Download)

Saiba mais sobre o HTTP File Trigger e como utilizá-lo na Digibee Integration Platform.

O HTTP File Trigger pode ser usado para:

Upload: Enviar arquivos grandes (acima de 5 MB) para um pipeline via HTTP.
Download: Baixar arquivos grandes usando o método GET.

A seguir, você aprenderá a configurar o trigger para ambos os casos.

Parâmetros

Configure o trigger utilizando os parâmetros abaixo. Os campos que aceitam expressões Double Braces estão marcados na coluna Suporta DB.

Parâmetro

Descrição

Tipo

Suporta DB

Padrão

Methods

Define os métodos aceitos pelo pipeline.

String

❌

POST, PUT, GET, PATCH and DELETE

Response Headers

Cabeçalhos retornados pelo endpoint quando o processamento do pipeline é concluído. Evite caracteres especiais nas chaves, pois podem causar falhas em proxies e gateways.

Pares chave-valor

✅

N/A

Add Cross-Origin Resource Sharing (CORS)

Quando habilitado, permite adicionar cabeçalhos CORS que serão retornados pelo endpoint após o processamento do pipeline.

Use vírgula (,) para separar múltiplos valores em um cabeçalho, sem espaços antes ou depois da vírgula. Evite caracteres especiais nas chaves dos cabeçalhos, pois podem causar falhas em proxies ou gateways.

Booleano

❌

False

CORS Headers

Define CORS especificamente para o pipeline e suas restrições.

Para configurá-lo globalmente (em vez de individualmente por pipeline), consulte a política CORS HTTP Header.

Pares chave-valor

❌

N/A

Form Data Uploads

Habilita ou desabilita o recebimento de uploads via form data (multipart/form-data).

Booleano

❌

True

Body Uploads

Habilita ou desabilita o recebimento de uploads via body.

Booleano

❌

True

Body Upload Content Types

Define os tipos de conteúdo permitidos pelo pipeline para uploads via body.

String

❌

application/pdf, application/jpeg

Response Content Types

Define os tipos de conteúdo permitidos na resposta do pipeline. Exemplo: determina o formato da resposta.

String

✅

text/xml, application/xml

Maximum Timeout

Tempo máximo (em milissegundos) que o pipeline pode levar para processar informações antes de retornar uma resposta. Limite: 900000.

Se o processamento ultrapassar esse limite, a requisição é encerrada e retorna um código 500 sem corpo de resposta.

Integer

❌

30000

Maximum Request Size

Define o tamanho máximo do arquivo na requisição de upload (em MB). Máximo: 100 MB.

Integer

❌

100

External API

Quando habilitado, publica a API em um gateway externo.

Booleano

❌

True

Internal API

Quando habilitado, publica a API em um gateway interno.

Booleano

❌

False

mTLS enabled API

Quando habilitado, publica a API em um gateway dedicado com mTLS, com um host de acesso diferente.

O pipeline pode ter as opções External API e Internal API habilitadas, mas recomenda-se mantê-las desativadas.

Este parâmetro não oferece suporte a API Key, JWT ou Basic Auth. Para habilitá-los no seu realm, entre em contato com o Suporte.

Booleano

❌

False

API Key

Quando habilitado, o endpoint só pode ser acessado se uma API Key tiver sido previamente configurada na Plataforma Digibee.

Booleano

❌

False

Token JWT

Quando habilitado, solicita o token para consumo da API.

Booleano

❌

False

Basic Auth

Quando habilitado, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição.

Essa configuração pode ser registrada previamente pela página Consumers na Plataforma da Digibee.

Booleano

❌

False

Additional API Routes

Quando habilitado, permite adicionar novas rotas.

Booleano

❌

False

Remove Digibee Prefix from Route

Remove o prefixo padrão da rota da Digibee /pipeline/{realm}/v{n} da rota do pipeline.

Disponível apenas quando os parâmetros External API e Internal API estão desativados e os parâmetros mTLS enabled API e Additional API Routes estão habilitados.

Booleano

❌

False

Routes

Define rotas personalizadas.

String

❌

N/A

Rate Limit

Quando habilitado, aplica limitação de taxa ao gateway da API.

Disponível se API Key ou Basic Auth estiverem habilitados.

Booleano

❌

False

Limit by

Define a entidade à qual os limites serão aplicados.

String

❌

API

Aggregate by

Define a entidade usada para agregação dos limites. Opções: Consumers e Credential (API Key, Basic Auth).

String

❌

Consumer

Options

Define o limite de requisições permitidas dentro de um intervalo de tempo.

Opções de limite e intervalo

❌

N/A

Interval

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

String

❌

second

Limit

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

Integer

❌

N/A

Allow Redelivery Of Messages

Quando habilitado, permite a reenviar mensagens em caso de falha do Pipeline Engine.

Booleano

❌

False

HTTP File Trigger em ação

Upload

Cenário 1: `POST` com tipo de conteúdo de arquivo `multipart/form-data`

Se você quiser enviar um arquivo maior que 5 MB, chame o endpoint do pipeline configurado com um HTTP File Trigger usando uma requisição POST com o tipo de conteúdo de arquivo multipart/form-data. Isso permite que o pipeline processe o arquivo. Siga estes passos:

Habilite a opção Form Data Uploads no HTTP File Trigger.
Faça a implantação (deploy) do pipeline.
Crie um Consumer e configure o acesso ao pipeline.
Chame o pipeline com o comando 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: Refere-se a um arquivo local.
realm_name: Realm onde o pipeline está localizado.
generated_token: API Key gerada pelo consumer criado.

O pipeline receberá arquivos [ ] array contendo:

fileName
param
contentType

Isso permite que os arquivos sejam 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"    
    }  
  ]
}

Cenário 2: `POST` com tipo de conteúdo `multipart/form-data` de vários arquivos.

Suponha que você tenha vários arquivos maiores que 5 MB. Você pode chamar um endpoint de um pipeline configurado com um HTTP File Trigger usando uma requisição POST com um tipo de conteúdo multipart/form-data, permitindo que o pipeline processe esses arquivos. Siga estes passos:

Habilite a opção Form Data Uploads no HTTP File Trigger.
Faça a implantação (deploy) do pipeline.
Crie um Consumer e configure o acesso ao pipeline.
Chame o pipeline com o comando 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: Refere-se a um arquivo local.
file_name2: Refere-se a um arquivo local.
realm_name: Realm onde o pipeline está localizado.
generated_token: Refere-se a API Key gerada pelo consumidor criado.

O pipeline receberá arquivos [ ] array contendo:

fileName
originalFileName
param
charset
contentLength
contentType

Isso permite que os arquivos sejam 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 tipo de conteúdo e body com mais de 5MB

Suponha que você tenha vários arquivos maiores que 5 MB. Você pode chamar um endpoint de pipeline configurado com um HTTP File Trigger usando uma requisição POST com qualquer tipo de conteúdo, permitindo que o pipeline processe esses arquivos. Siga estes passos:

Habilite a opção Body Uploads no HTTP File Trigger.
Faça a implantação (deploy) do pipeline.
Crie um Consumer e configure-o para ter acesso ao pipeline.
Chame o pipeline utilizando o seguinte comando cURL:

curl -d '@file_name1' https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'

O pipeline receberá arquivos [ ] array contendo:

fileName
param
charset
contentType

Isso permite que os arquivos sejam 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"
    }
  ]
}

Download

Cenário: `GET` com qualquer tipo de conteúdo

Suponha que você tenha um arquivo com mais de 5 MB. Você pode chamar um endpoint de pipeline configurado com um HTTP File Trigger usando uma solicitação GET com qualquer tipo de conteúdo. O pipeline recebe e processa o arquivo, retornando-o de acordo com o tipo de conteúdo de saída e seu conteúdo original. Siga estes passos:

Inclua o método GET e especifique os Response Content Types no HTTP File Trigger.
Adicione um File Reader ao pipeline para pesquisar o arquivo a ser processado. Por exemplo, você pode configurar um conector WGet para recuperar um arquivo de uma URL enviada ao endpoint durante uma chamada.
Insira um JSON Generator como a última etapa do seu pipeline para produzir um JSON no seguinte formato:

{ 
    "file": "file-download.pdf",
    "Content-Type": "application/pdf"
}

Faça a implantação (deploy) do pipeline.
Crie um Consumer e configure-o para ter acesso ao pipeline.
Chame o pipeline utilizando o seguinte comando cURL:

curl https://godigibee.io/pipeline/realm_name/v1/pipeline_name -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token' -H 'urlDownload: http://url/path'

realm_name: Refere-se ao realm onde o pipeline está localizado.
generated_token: Refere-se à API Key gerada pelo consumer criado recentemente.
urlDownload: Refere-se ao parâmetro enviado ao conector WGet para preencher o campo URL. O atributo é opcional, mas permite uma abordagem mais flexível usando Double Braces. Funciona perfeitamente se o caminho for definido diretamente no conector WGet.

Resposta do HTTP File Trigger

Upload - Resposta

Para definir o formato da resposta do pipeline, adicione um conector de transformação, por exemplo o Transformer (JOLT), como a última etapa do pipeline e configure a resposta desejada:

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

Limitações de resposta para payloads acima de 5 MB

Para cargas (payloads) maiores que 5 MB, recomenda-se que o pipeline retorne um arquivo, em vez de um payload. Use o conector File Writer para gerar o arquivo e referencie-o na resposta do pipeline usando a propriedade file, em vez de body:

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

Download - Resposta

Para definir o formato da resposta do pipeline, adicione um conector de transformação, por exemplo o Transformer (JOLT), como a última etapa do pipeline e configure a resposta desejada:

{  
    "file": "file-download.pdf",  
    "code": 200,  
    "Content-Type": "application/pdf"
}

O HTTP File Trigger também pode responder com corpos que não sejam arquivos, de forma semelhante ao HTTP Trigger. Para isso, a última etapa do pipeline deve ter a seguinte estrutura:

{ 
    "body": "information that will be written in the endpoint output", 
    "Content-Type": "body content type", 
    "code": <a HTTP return code>
}

Propriedades das respostas

A mesma estrutura de resposta se aplica tanto a cenários de upload quanto de download.

code: Código de status HTTP retornado pelo endpoint após o término da requisição.
body: Corpo da mensagem de resposta. Este campo deve ser uma string. Se for necessário enviar dados em JSON, use a função TOSTRING.
content-type: tipo de conteúdo do corpo da resposta. Todos os tipos de conteúdo são suportados, mas devem ser declarados no campo Response Content Types.

Boas práticas

Configuração global de autenticação

O parâmetro de configuração global reforça a autenticação de todos os pipelines usando o HTTP File Trigger. Quando ativado, os pipelines só podem ser publicados se pelo menos um método de autenticação (API Key or Basic Auth) é configurado.

Remove Digibee Prefix from Route

Ao remover o prefixo padrão e definir a rota por meio do parâmetro Additional API Route certifique-se de não usar uma rota já atribuída a outro pipeline. Se houver várias versões principais do mesmo pipeline, lembre-se de que o controle de versão da rota deve ser gerenciado manualmente, pois não há um caminho de controle de versão automático (por exemplo: /pipeline/realm/v1/).

Rate Limit

Ative o Rate Limit para restringir o número de requisições de API dentro de um intervalo específico. Use a configuração recomendada:

Limit by: API
Aggregate by: Credential (API Key, Basic Auth)
Options:
- Interval: second → Limit: 100
- Interval: minute → Limit: 1000
- Interval: hour → Limit: 5000

Se a API incluir caminhos adicionais, o limite se aplicará a todos eles coletivamente. Para ativar o Rate Limit, a API deve usar uma chave de API ou Basic Auth, permitindo a agregação por grupos de credenciais (opção Consumer) ou credenciais individuais (opção Credentials).

Se vários parâmetros de intervalo tiverem o mesmo valor, apenas um será considerado. O parâmetro Limit deve ser sempre maior que zero. Configurações de limitação de taxa incorretas ou incompletas serão ignoradas e um log de aviso será gerado. Você pode visualizar este log na páginas de Pipeline Logs.

AnteriorHTTP Trigger PróximoHTTP File Trigger - Downloads

Atualizado há 8 dias

Isto foi útil?

Parâmetros

HTTP File Trigger em ação

Upload

Cenário 1: POST com tipo de conteúdo de arquivo multipart/form-data

Cenário 2: POST com tipo de conteúdo multipart/form-data de vários arquivos.

Cenário 3: POST com qualquer tipo de conteúdo e body com mais de 5MB

Download

Cenário: GET com qualquer tipo de conteúdo

Resposta do HTTP File Trigger

Upload - Resposta

Limitações de resposta para payloads acima de 5 MB

Download - Resposta

Propriedades das respostas

Boas práticas

Configuração global de autenticação

Remove Digibee Prefix from Route

Rate Limit

Cenário 1: `POST` com tipo de conteúdo de arquivo `multipart/form-data`

Cenário 2: `POST` com tipo de conteúdo `multipart/form-data` de vários arquivos.

Cenário 3: `POST` com qualquer tipo de conteúdo e body com mais de 5MB

Cenário: `GET` com qualquer tipo de conteúdo