# HTTP File Trigger (Upload and Download)

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**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces) estão marcados na coluna **Suporta DB**.

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Padrão </th></tr></thead><tbody><tr><td><strong>Methods</strong></td><td>Define os métodos aceitos pelo pipeline.</td><td>String</td><td>❌</td><td><code>POST</code>, <code>PUT</code>, <code>GET</code>, <code>PATCH</code> and <code>DELETE</code></td></tr><tr><td><strong>Response Headers</strong></td><td>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.</td><td>Pares chave-valor</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Add Cross-Origin Resource Sharing (CORS)</strong></td><td><p>Quando habilitado, permite adicionar cabeçalhos CORS que serão retornados pelo endpoint após o processamento do pipeline.</p><p>Use vírgula (<code>,</code>) 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.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>CORS Headers</strong></td><td><p>Define CORS especificamente para o pipeline e suas restrições.</p><p>Para configurá-lo globalmente (em vez de individualmente por pipeline), consulte a política <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/governance/policies/transformation/cors-http-header">CORS HTTP Header.</a></p></td><td>Pares chave-valor</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Form Data Uploads</strong></td><td>Habilita ou desabilita o recebimento de uploads via form data (multipart/form-data).</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Uploads</strong></td><td>Habilita ou desabilita o recebimento de uploads via body.</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Upload Content Types</strong></td><td>Define os tipos de conteúdo permitidos pelo pipeline para uploads via body.</td><td>String</td><td>❌</td><td><code>application/pdf</code>, <code>application/jpeg</code></td></tr><tr><td><strong>Response Content Types</strong></td><td>Define os tipos de conteúdo permitidos na resposta do pipeline. Exemplo: determina o formato da resposta.</td><td>String</td><td>✅</td><td><code>text/xml</code>, <code>application/xml</code></td></tr><tr><td><strong>Maximum Timeout</strong></td><td><p>Tempo máximo (em milissegundos) que o pipeline pode levar para processar informações antes de retornar uma resposta. Limite: <code>900000</code>.</p><p>Se o processamento ultrapassar esse limite, a requisição é encerrada e retorna um código <code>500</code> sem corpo de resposta.</p></td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Maximum Request Size</strong></td><td>Define o tamanho máximo do arquivo na requisição de upload (em MB). Máximo: 100 MB.</td><td>Integer</td><td>❌</td><td><code>100</code></td></tr><tr><td><strong>External API</strong></td><td>Quando habilitado, publica a API em um gateway externo.</td><td>Booleano</td><td>❌</td><td>True</td></tr><tr><td><strong>Internal API</strong></td><td>Quando habilitado, publica a API em um gateway interno.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>mTLS enabled API</strong></td><td><p>Quando habilitado, publica a API em um gateway dedicado com mTLS, com um host de acesso diferente.</p><p>O pipeline pode ter as opções <strong>External API</strong> e <strong>Internal API</strong> habilitadas, mas recomenda-se mantê-las desativadas.</p><p>Este parâmetro não oferece suporte a <strong>API Key</strong>, <strong>JWT</strong> ou <strong>Basic Auth</strong>. Para habilitá-los no seu realm, <a href="https://app.gitbook.com/s/3ANg0NQQeslB7Og5K7Ah/help-and-faq/support">entre em contato com o Suporte</a>.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>API Key</strong></td><td>Quando habilitado, o endpoint só pode ser acessado se uma API Key tiver sido previamente configurada na Plataforma Digibee.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Token JWT</strong></td><td>Quando habilitado, solicita o token para consumo da API.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Basic Auth</strong></td><td><p>Quando habilitado, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição.</p><p>Essa configuração pode ser registrada previamente pela página <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers">Consumers</a> na Plataforma da Digibee.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Additional API Routes</strong></td><td>Quando habilitado, permite adicionar novas rotas.</td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Remove Digibee Prefix from Route</strong></td><td><p>Remove o prefixo padrão da rota da Digibee <code>/pipeline/{realm}/v{n}</code> da rota do pipeline. </p><p>Disponível apenas quando os parâmetros <strong>External API</strong> e <strong>Internal API</strong> estão desativados e os parâmetros <strong>mTLS enabled API</strong> e <strong>Additional API Routes</strong> estão habilitados.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Routes</strong></td><td>Define rotas personalizadas.</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Rate Limit</strong></td><td><p>Quando habilitado, aplica limitação de taxa ao gateway da API.</p><p>Disponível se <strong>API Key</strong> ou <strong>Basic Auth</strong> estiverem habilitados.</p></td><td>Booleano</td><td>❌</td><td>False</td></tr><tr><td><strong>Limit by</strong></td><td>Define a entidade à qual os limites serão aplicados.</td><td>String</td><td>❌</td><td>API</td></tr><tr><td><strong>Aggregate by</strong></td><td>Define a entidade usada para agregação dos limites. Opções: <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers">Consumers e Credential</a> (API Key, Basic Auth).</td><td>String</td><td>❌</td><td>Consumer</td></tr><tr><td><strong>Options</strong></td><td>Define o limite de requisições permitidas dentro de um intervalo de tempo.</td><td>Opções de limite e intervalo</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Interval</strong></td><td>Define o intervalo de tempo para o limite de requisições. Opções: <strong>second</strong>, <strong>minute</strong>, <strong>hour</strong>, <strong>day</strong> e <strong>month</strong>.</td><td>String</td><td>❌</td><td>second</td></tr><tr><td><strong>Limit</strong></td><td>Define o número máximo de requisições que os usuários podem fazer dentro do intervalo especificado.</td><td>Integer</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Allow Redelivery Of Messages</strong></td><td>Quando habilitado, permite a reenviar mensagens em caso de falha do Pipeline Engine.</td><td>Booleano</td><td>❌</td><td>False</td></tr></tbody></table>

## HTTP File Trigger em ação

### Upload

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

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:

1. Habilite a opção **Form Data Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers) e configure o acesso ao pipeline.
4. Chame o pipeline com o comando cURL:

```sh
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:

```json
{
  "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.&#x20;

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:

1. Habilite a opção **Form Data Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers) e configure o acesso ao pipeline.
4. Chame o pipeline com o comando cURL:

```sh
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:

```json
{
  "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:

1. Habilite a opção **Body Uploads** no **HTTP File Trigger**.
2. Faça a implantação (deploy) do pipeline.
3. Crie um [Consumer ](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers)e configure-o para ter acesso ao pipeline.
4. Chame o pipeline utilizando o seguinte comando cURL:

```sh
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:

```json
{
  "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:

1. Inclua o método `GET` e especifique os **Response Content Types** no HTTP File Trigger.
2. Adicione um [File Reader ](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/files/file-reader)ao pipeline para pesquisar o arquivo a ser processado. Por exemplo, você pode configurar um conector [WGet](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/wget) para recuperar um arquivo de uma URL enviada ao endpoint durante uma chamada.
3. Insira um [JSON Generator](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator) como a última etapa do seu pipeline para produzir um JSON no seguinte formato:

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

4. Faça a implantação (deploy) do pipeline.
5. Crie um [Consumer ](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers)e configure-o para ter acesso ao pipeline.
6. Chame o pipeline utilizando o seguinte comando cURL:

```sh
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.&#x20;
* **`generated_token`**: Refere-se à **API Key** gerada pelo consumer criado recentemente.&#x20;
* **`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](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/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)**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/jolt-v2), como a última etapa do pipeline e configure a resposta desejada:

```json
{  
    "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** ](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/files/file-writer)para gerar o arquivo e referencie-o na resposta do pipeline usando a propriedade `file`, em vez de `body`:

```json
{
"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)**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/jolt-v2), como a última etapa do pipeline e configure a resposta desejada:

```json
{  
    "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](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/http). Para isso, a última etapa do pipeline deve ter a seguinte estrutura:

```json
{ 
    "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](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/double-braces-functions#de-string).
* **`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**).

{% hint style="info" %}
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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/pipeline-logs).
{% endhint %}