개요

UnityWebRequest 는 유니티에서 HTTP 통신을 수행하기 위한 클래스로, 웹 서버와 데이터를 주고 받을 때 사용한다.

이에 대한 개념을 한번 짚고 넘어가보자.

개념

UnityEngine.Networking 네임스페이스 안에 있는 클래스로,

HTTP 통신(GET, POST, PUT, DELETE 등)을 수행하여

웹 서버와 데이터를 주고 받을 수 있게 한다.

보통 유니티에서 엑셀 데이터를 가져올 떄나, 서버에서 텍스트, 이미지 등을 받아올 때 쓰이거나

서버에 데이터를 POST 할 때도 유용하게 쓰인다.

HTTP란?

HyperText Transfer Protocol의 줄임말로, 클라이언트와 서버간 데이터를 주고 받기 위한 통신 방식이다.

아래는 주요 HTTP 메서드와 서버 응답코드를 정리하였다.

메서드	설명	용도
GET	서버로부터 데이터 가져오기	파일 다운로드, 정보 조회
POST	서버에 새로운 데이터 전송	회원가입, 로그인, 업로드 등
PUT	기존 데이터를 수정	데이터 전체 갱신
DELETE	데이터를 삭제	특정 데이터 제거
PATCH	일부 데이터 부분 수정	한 필드만 수정 등

상태코드	의미	설명
200 OK	성공	요청 정상 처리
201 Created	생성됨	POST로 리소스 생성 성공
400 Bad Request	잘못된 요청	요청 형식 오류
401 Unauthorized	인증 실패	토큰 누락 등
403 Forbidden	권한 없음	접근 금지
404 Not Found	못 찾음	URL 오류
500 Internal Server Error	서버 오류	예외 발생 등

주요 메서드 및 용도

항목	설명	용도
Get	서버에서 데이터 받기	랭킹, 설정파일 다운로드 등
Post	서버에 데이터 보내기	로그인, 폼 제출 등
Put	서버 데이터 전체 수정	프로필 수정 등
Delete	데이터 삭제 요청	친구 삭제 등
SendWebRequest()	요청 전송	Coroutine에서 비동기로 실행
DownloadHandlerBuffer	텍스트/JSON 받기	CSV, 로그 등
DownloadHandlerTexture	이미지 받기	캐릭터 사진 등
UploadHandlerRaw	JSON 등 바이트 업로드	API 호출, 저장 요청

중요한 메서드 몇 개만 정리해보자.

UnityWebRequest.Get(string url)

GET 요청을 보내 서버(url)로부터 데이터를 가져오는 메소드로,

url 뒤에 쿼리 스트링을 붙이면 다양한 요청이 가능하다.

주로 JSON, CSV, 이미지 등 파일을 다운로드할 때나, API에서 데이터 조회를 할 때 쓰인다.

IEnumerator GetExample()
{
    string url = "https://myserver.com/data.json";
    UnityWebRequest request = UnityWebRequest.Get(url);

    yield return request.SendWebRequest();

    if (request.result == UnityWebRequest.Result.Success)
    {
        Debug.Log("받은 데이터: " + request.downloadHandler.text);
    }
    else
    {
        Debug.LogError("에러: " + request.error);
    }
}

UnityWebRequest.Post(string url, WWWForm form)

POST요청을 보내서, 서버에 데이터를 전송할 때 사용한다.

벡엔드 개발에서 보통 로그인 요청이나 회원가입을 구현할 때 많이 쓰이며,

랭킹 기록을 위한 점수를 제출할 때도 쓰일 수 있다.

IEnumerator PostExample()
{
    string url = "https://myserver.com/login";
    WWWForm form = new WWWForm();
    form.AddField("id", "test");
    form.AddField("pw", "1234");

    UnityWebRequest request = UnityWebRequest.Post(url, form);

    yield return request.SendWebRequest();

    if (request.result == UnityWebRequest.Result.Success)
        Debug.Log("서버 응답: " + request.downloadHandler.text);
    else
        Debug.LogError("전송 실패: " + request.error);
}

WWWForm은 일반적인 key-value 방식의 폼 데이터 전송용이다.

SendWebRequest()

UnityWebRequest 는 요청을 서버로 전송하는 역할로

비동기 방식으로 작동한다.

일반적으로는 코루틴의 yield return과 함께 사용하는 것이 권장된다.

이 부분은 상황에 따라 조금 다른데,

에디터 전용 툴인 경우(Unity 에디터에서만 사용),

코루틴 없이 while (!req.isDone) { } 으로 사용해도 무방하다.

근데 빌드된 게임 내에서 실행 중에는

이 경우 코루틴을 사용하지 않으면 런타임에 매우 위험할 수 있기에

코루틴을 통해 유니티 메인 루프에 영향을 주지 않는 것이 바람직하다.

DownloadHandlerBuffer()

텍스트 기반 데이터를 받기 위한 핸들러로,

위 코드로 데이터를 받으면 request.downloadHandler.text 로 읽을 수 있다.

UnityWebRequest request = new UnityWebRequest(url, "GET");
request.downloadHandler = new DownloadHandlerBuffer();

DownloadHandlerTexture

이미지를 다운로드 할 때 사용하는 핸들러다.

UnityWebRequest request = UnityWebRequestTexture.GetTexture(url);
yield return request.SendWebRequest();
Texture2D tex = DownloadHandlerTexture.GetContent(request);

DownloadHandlerTexture.GetContent(request)는 결과를 바로 Texture2D로 반환한다.