> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extensão vsql_http para MySQL

> A extensão vsql_http faz requisições GET, POST, PUT, PATCH e DELETE de dentro de uma consulta MySQL, retornando cada resposta como JSON.

O `vsql_http` faz requisições HTTP de dentro de uma consulta. Um trigger pode
chamar um webhook, um `SELECT` pode enriquecer linhas a partir de uma API, e um
evento agendado pode enviar um resumo para algum lugar, sem nenhuma camada de
aplicação no meio. Ele é construído sobre a libcurl e retorna toda resposta
como JSON.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-http](https://github.com/villagesql/vsql-http) |
| **Licença** | GPL-2.0 |

## Instalar

O `vsql_http.veb` já está no diretório `lib/veb/` do servidor se você instalou
o VillageSQL com o script de instalação, a imagem Docker ou um tarball de
release. Instale-o no servidor com uma única instrução:

```sql theme={null}
INSTALL EXTENSION vsql_http;
```

Confirme que ele está lá:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_http';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_http      |
+----------------+
```

Para compilá-lo você mesmo, siga as instruções de compilação no
[repositório](https://github.com/villagesql/vsql-http).

## O que ela adiciona

Toda função de requisição retorna um objeto JSON com quatro campos: `status`,
`content_type`, `headers` e `content`. Uma requisição que não consegue ser
concluída, como uma conexão recusada ou um timeout, retorna `NULL` e gera um
aviso com a mensagem de erro do curl:

```
Warning 3200 VDF error in function 'http_get': Couldn't connect to server
```

| Função | Retorna | O que faz |
| - | - | - |
| `http_get(url)` | texto | Uma requisição GET, com a resposta como JSON |
| `http_post(url, content_type, body)` | texto | Uma requisição POST com um corpo |
| `http_put(url, content_type, body)` | texto | Uma requisição PUT com um corpo |
| `http_patch(url, content_type, body)` | texto | Uma requisição PATCH com um corpo |
| `http_delete(url)` | texto | Uma requisição DELETE |
| `http_request(method, url, headers, body, content_type, options)` | texto | Qualquer método, com os seus próprios cabeçalhos e opções como JSON |
| `url_encode(s)` | texto | Codifica uma string com percentuais para uso em uma URL |
| `url_decode(s)` | texto | Reverte `url_encode` |

O argumento `method` do `http_request` reconhece GET, HEAD, POST, PUT, DELETE,
CONNECT, OPTIONS, TRACE e PATCH sem distinguir maiúsculas de minúsculas e os
envia em maiúsculas; qualquer outro método é enviado exatamente como foi dado.

## Exemplo

Busque uma URL e leia dois campos da resposta:

```sql theme={null}
SET @r = CONVERT(http_get('https://villagesql.com/robots.txt') USING utf8mb4);

SELECT JSON_EXTRACT(@r, '$.status') AS status,
       JSON_UNQUOTE(JSON_EXTRACT(@r, '$.content_type')) AS content_type;
```

```
+--------+---------------------------+
| status | content_type              |
+--------+---------------------------+
| 200    | text/plain; charset=utf-8 |
+--------+---------------------------+
```

Monte uma query string com segurança:

```sql theme={null}
SELECT url_encode('hello world & more') AS encoded;
```

```
+----------------------------+
| encoded                    |
+----------------------------+
| hello%20world%20%26%20more |
+----------------------------+
```

> [!NOTE]
>
> No VillageSQL 0.0.6 e anteriores, a resposta carrega o conjunto de caracteres
> binary. Uma função JSON ou uma coluna `JSON` a rejeita, então o exemplo acima
> sem o seu `CONVERT` falha ali com
> `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
>     SET 'binary'.` Dentro de `JSON_OBJECT()` ou `JSON_ARRAY()` ela é aceita, mas
> codificada em base64. Mantenha o `CONVERT(... USING utf8mb4)` nessas
> versões; ele não é necessário no 0.0.7 e posteriores, e é inofensivo ali.

> [!WARNING]
>
> Uma requisição bloqueia a instrução que a fez, por até 30 segundos por
> padrão. Somente o `http_request` pode encurtar isso, por meio do seu
> argumento de opções, como em `'{"timeout": 5}'`. Uma chamada por linha
> transforma uma varredura de tabela em uma série de idas e voltas pela rede,
> então mantenha essas chamadas longe de conjuntos de resultados grandes.

## Veja também

* [Fazendo requisições HTTP a partir do MySQL](https://villagesql.com/docs/en/guides/http-requests-in-mysql.md) — timeouts, tratamento de erros e leitura da resposta
* [Enviando webhooks a partir do MySQL](https://villagesql.com/docs/en/guides/http-webhooks.md) — disparar uma requisição a partir de um trigger
* [Enriquecendo linhas a partir de uma API REST](https://villagesql.com/docs/en/guides/rest-api-enrichment.md) — juntar uma consulta a um serviço externo
* [Instalar extensões](https://villagesql.com/docs/pt-BR/extensions/install.md) — como o `INSTALL EXTENSION` funciona e onde o servidor procura um bundle
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-http](https://github.com/villagesql/vsql-http) — código-fonte, instruções de compilação e as limitações conhecidas


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.