> ## 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.

# MySQL용 vsql_http 확장 기능

> vsql_http 확장 기능은 MySQL 쿼리 안에서 GET, POST, PUT, PATCH, DELETE 요청을 보내고 각 응답을 JSON으로 반환합니다.

`vsql_http`는 쿼리 안에서 HTTP 요청을 보냅니다. 트리거가 웹훅을 호출하고,
`SELECT`가 API에서 행을 보강하고, 예약된 이벤트가 요약을 어딘가로 보낼 수
있으며, 그 사이에 애플리케이션 계층이 필요 없습니다. libcurl 기반으로 빌드되었고
모든 응답을 JSON으로 반환합니다.

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-http](https://github.com/villagesql/vsql-http) |
| **라이선스** | GPL-2.0 |

## 설치

설치 스크립트, Docker 이미지 또는 릴리스 tarball로 VillageSQL을 설치했다면
`vsql_http.veb`는 이미 서버의 `lib/veb/` 디렉터리에 있습니다. 문 하나로 서버에
설치하세요:

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

설치되었는지 확인합니다:

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

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

직접 빌드하려면 [저장소](https://github.com/villagesql/vsql-http)의 빌드
지침을 따르세요.

## 추가되는 기능

모든 요청 함수는 네 개의 필드 `status`, `content_type`, `headers`, `content`를
가진 JSON 객체 하나를 반환합니다. 연결 거부나 시간 초과처럼 완료할 수 없는
요청은 `NULL`을 반환하고 curl의 오류 메시지를 담은 경고를 발생시킵니다:

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

| 함수 | 반환값 | 설명 |
| - | - | - |
| `http_get(url)` | text | GET 요청. 응답은 JSON |
| `http_post(url, content_type, body)` | text | 본문이 있는 POST 요청 |
| `http_put(url, content_type, body)` | text | 본문이 있는 PUT 요청 |
| `http_patch(url, content_type, body)` | text | 본문이 있는 PATCH 요청 |
| `http_delete(url)` | text | DELETE 요청 |
| `http_request(method, url, headers, body, content_type, options)` | text | 임의의 메서드. 헤더와 옵션을 JSON으로 직접 지정 |
| `url_encode(s)` | text | URL에 쓸 수 있도록 문자열을 퍼센트 인코딩 |
| `url_decode(s)` | text | `url_encode`를 되돌림 |

`http_request`의 `method` 인수는 GET, HEAD, POST, PUT, DELETE, CONNECT,
OPTIONS, TRACE, PATCH를 대소문자 구분 없이 매칭하여 대문자로 보냅니다. 그 외의
메서드는 지정한 그대로 보냅니다.

## 예제

URL을 가져와서 응답에서 필드 두 개를 읽습니다:

```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 |
+--------+---------------------------+
```

쿼리 문자열을 안전하게 만듭니다:

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

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

> [!NOTE]
>
> VillageSQL 0.0.6 이하에서는 응답이 binary 문자 집합을 가집니다. JSON 함수나
> `JSON` 열이 이를 거부하므로, 위의 예제에서 `CONVERT`를 빼면 해당 버전에서
> `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
>     SET 'binary'.` 오류로 실패합니다. `JSON_OBJECT()`나 `JSON_ARRAY()` 안에서는
> 허용되지만 대신 base64로 인코딩됩니다. 해당 버전에서는
> `CONVERT(... USING utf8mb4)`를 유지하세요. 0.0.7 이상에서는 필요하지 않지만
> 해롭지도 않습니다.

> [!WARNING]
>
> 요청은 이를 보낸 문을 기본적으로 최대 30초 동안 차단합니다. `http_request`만
> 옵션 인수(예: `'{"timeout": 5}'`)로 이 시간을 줄일 수 있습니다. 행마다 한 번씩
> 호출하면 테이블 스캔이 연속된 네트워크 왕복으로 바뀌므로, 큰 결과 집합에서는
> 이 호출을 피하세요.

## 참고 항목

* [MySQL에서 HTTP 요청 보내기](https://villagesql.com/docs/en/guides/http-requests-in-mysql.md) — 시간 제한, 오류 처리, 응답 읽기
* [MySQL에서 웹훅 보내기](https://villagesql.com/docs/en/guides/http-webhooks.md) — 트리거에서 요청 보내기
* [REST API로 행 보강하기](https://villagesql.com/docs/en/guides/rest-api-enrichment.md) — 쿼리를 외부 서비스와 조인하기
* [확장 기능 설치](https://villagesql.com/docs/ko/extensions/install.md) — `INSTALL EXTENSION`의 동작 방식과 서버가 번들을 찾는 위치
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-http](https://github.com/villagesql/vsql-http) — 소스, 빌드 지침, 알려진 제한 사항


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