# HttpService

HttpService : `Instance`

## Overview

외부 웹 서비스와의 통신을 위한 HTTP 요청 기능을 제공합니다. 이를 활용하면 분석 시스템 연동, 클라우드 기반 데이터 처리, 외부 서버 환경 설정 반영, 실시간 데이터 전송 등 다양한 기능을 월드에 통합할 수 있습니다.

또한 JSON 형식을 사용하는 API와 교류할 때 JSONEncode 및 JSONDecode 메서드를 통해 데이터를 간단히 직렬화하거나 역직렬화할 수 있습니다.

안정적이고 안전한 월드 환경을 유지하기 위해, 반드시 신뢰성과 보안성이 검증된 외부 플랫폼에만 HTTP 요청을 전송할 것을 권장합니다.

## Properties

### HttpEnabled

`boolean`

HttpService를 통해 외부 웹 서비스와 통신할 수 있도록 허용하는 설정입니다.

이 값을 true로 지정하면 스크립트에서 GetAsync, PostAsync, RequestAsync 메서드를 사용하여 외부 서버로 HTTP 요청을 전송할 수 있습니다.

해당 옵션은 스튜디오의 Game Settings 메뉴에서도 활성화할 수 있습니다.

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

print(HttpService.HttpEnabled)
```

## Methods

### GenerateGUID

실행 환경 전체에서 단 한 번만 UUID 문자열을 생성하며, 이후 모든 호출에서 동일한 UUID를 반환합니다.

생성된 식별자는 16바이트의 데이터를 32개의 16진수 문자로 표현한 뒤, 8-4-4-4-12 형태로 구분하여 총 36자의 문자열 형태(예: 123e4567-e89b-12d3-a456-426655440000)로 제공합니다.

#### Parameters

| `boolean` InWrapInCurlyBraces | 문자열 앞뒤에 중괄호를 포함할지 여부입니다. (기본값: false) |
| ----------------------------- | ------------------------------------- |

#### Return

| `string` | 생성된 UUID입니다. |
| -------- | ------------ |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local Result = HttpService:GenerateGUID(false)

print(Result)
```

### GetAsync

HTTP GET 요청을 전송하는 간단한 사용 방식으로, RequestAsync와 비슷하게 동작하지만 요청 정보를 개별 인자로 전달하고 응답 데이터 중 본문만 반환합니다. 따라서 편의상 빠르게 GET 요청을 보내야 할 때 적합하며, 보다 정교한 제어가 필요한 경우에는 RequestAsync를 사용하는 것이 더 바람직합니다.

NoCache 값을 true로 지정하면 동일한 주소로 보낸 과거 요청의 캐시를 사용하지 않고, 매번 새롭게 서버에 요청을 전송하도록 동작합니다.

#### Parameters

| `string` InUrl      | 요청할 웹 서버의 URL입니다.         |
| ------------------- | ------------------------- |
| `boolean` InNoCache | 캐시 사용 여부입니다. (기본값: false) |
| `Value` InHeaders   | HTTP 요청에 포함할 헤더 정보입니다.    |

#### Return

| `string` | GET 요청에 대해 서버가 반환한 응답 데이터입니다. |
| -------- | ----------------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local baseUrl = "HTTP URL을 입력하세요"

local success, errorMessageOrResult, response = nil, nil, nil

success, errorMessageOrResult = pcall(function()
    response = HttpService:GetAsync(baseUrl)
end)

print("Success : ", success)
print("ErrorMessageOrResult : ", errorMessageOrResult)
print("Response : ", response)
```

### JSONDecode

JSON 형식의 객체 또는 배열을 Lua 테이블로 변환합니다.

JSON 객체는 문자열 키 기반의 테이블로, JSON 배열은 1부터 시작하는 숫자 키 기반의 배열 형태로 변환됩니다.

모든 숫자는 부동소수(float) 값으로 해석되며, 중첩된 구조는 재귀적으로 변환됩니다.

비어 있는 JSON 객체나 배열은 빈 테이블로 반환됩니다.

#### Parameters

| `string` InInput | 변환할 JSON 형식의 데이터입니다. |
| ---------------- | -------------------- |

#### Return

| `Value` | 변환된 Lua 테이블 데이터입니다. |
| ------- | ------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local data = HttpService:JSONDecode(jsonData)
print(data)
```

### JSONEncode

Lua 테이블을 JSON 객체 또는 배열로 변환합니다.

nil 값은 JSON에 포함되지 않으며, inf와 nan 같은 특수 숫자도 변환되지만 이는 JSON 표준에 속하지 않기 때문에 외부 시스템과 연동할 때 호환성 문제가 생길 수 있습니다.

비어 있는 테이블은 빈 JSON 배열로 변환되며, 테이블 내부에 순환 참조가 존재할 경우 변환 과정에서 오류가 발생합니다.

#### Parameters

| `Value` InInput | 변환할 Lua 테이블 데이터입니다. |
| --------------- | ------------------- |

#### Return

| `string` | 변환된 JSON 형식의 데이터입니다. |
| -------- | -------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local data =
{
    ["message"] = "Hello OVERDARE!",
    ["data"] = 10,
}
local jsonData = HttpService:JSONEncode(data)
```

### PostAsync

HTTP POST 요청을 수행합니다. RequestAsync() 함수와 유사한 기능을 제공하지만, 요청 데이터를 하나의 딕셔너리가 아닌 개별 매개변수로 전달할 수 있으며, 응답 전체가 아닌 본문(body)만 반환합니다.

주로 간편한 코드 작성용으로 사용되며, 대부분의 상황에서는 RequestAsync() 함수를 사용하는 것이 더 바람직합니다.

또한 compress 옵션을 true로 설정하면, 대용량 요청 본문이 자동으로 gzip 형식으로 압축되어 전송 효율을 향상시킬 수 있습니다.

#### Parameters

| `string` InUrl                       | 요청할 웹 서버의 URL입니다.                                                 |
| ------------------------------------ | ----------------------------------------------------------------- |
| `string` InData                      | 전송할 데이터입니다.                                                       |
| `Enum.HttpContentType` InContentType | Content-Type 헤더 값을 조정하여 전송 형식을 지정할 수 있습니다. (기본값: ApplicationJson) |
| `boolean` InCompress                 | 데이터를 서버로 보낼 때 gzip 방식으로 압축 전송을 사용할지 여부입니다. (기본값: false)           |
| `Value` InHeaders                    | HTTP 요청에 포함할 헤더 정보입니다.                                            |

#### Return

| `string` | POST 요청에 대해 서버가 반환한 응답 데이터입니다. |
| -------- | ------------------------------ |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local baseUrl = "HTTP URL을 입력하세요"

local success, errorMessageOrResult, response = nil, nil, nil

success, errorMessageOrResult = pcall(function()
    local data =
    {
        ["message"] = "Hello OVERDARE!",
        ["data"] = 10,
    }
    local jsonData = HttpService:JSONEncode(data)

    local contentType = Enum.HttpContentType.ApplicationJson
    local compress = false
    local headers = {}
    response = HttpService:PostAsync(baseUrl, jsonData, contentType, compress, headers)
end)

print("Success : ", success)
print("ErrorMessageOrResult : ", errorMessageOrResult)
print("Response : ", response)
```

### RequestAsync

Sends an HTTP request using any method with the provided dictionary of information.

#### Parameters

| `Dictionary` InRequestOptions | URL, 메서드, 헤더, 본문 등 HTTP 요청에 필요한 정보를 키-값 형태로 담은 딕셔너리입니다. |
| ----------------------------- | ------------------------------------------------------- |

#### Return

| `Value` | HTTP 응답 정보를 키-값 형태로 담은 딕셔너리입니다. 성공 여부, 상태 코드, 응답 본문 등이 포함됩니다. |
| ------- | ------------------------------------------------------------- |

#### Code Samples

### UrlEncode

입력된 문자열 내의 예약 문자를 % 기호와 두 자리 16진수 코드로 변환하여, URL에서 안전하게 사용할 수 있는 퍼센트 인코딩(percent-encoding) 문자열을 생성합니다.

#### Parameters

| `string` InInput | 변환할 문자열(주소)입니다. |
| ---------------- | --------------- |

#### Return

| `string` | 변환된 문자열(주소)입니다. |
| -------- | --------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local Query = "Hello #OVERDARE#"
local Encoded = HttpService:UrlEncode(Query)

print(Encoded)
```

## Events

## See also

{% content-ref url="/pages/Q1FDgqzgcPy4GeN2cDPq" %}
[JSON과 HTTP 통신](/korean/manual/script-manual/events-and-communication/json-and-http.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/korean/development/api-reference/classes/httpservice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.