UnityWebRequest

 

공부 이유 :

LM studio를 이용하여 실시간 AI 대사를 NPC에게 부여해주기 위해.

 

UnityWebRequest 

 

UnityWebRequest 는 HTTP 요청을 구성하고  HTTP  리스폰스를 처리하기 위한 모듈식 시스템을 제공한다.

UnityWebRequest 시스템의 주요 목표는 Unity 게임이 최신 웹 브라우저 백 엔드와 상호작용할 수 있도록 하는 것이다.

또한 대량의 HTTP 요청, POST/PUT 스트리밍 작업, HTTP 헤더 및 동사의 완벽 제어 등 높은 기능을 지원한다.

 

시스템은 다음과 같이 두 레이어로 구성된다.

 

• 고급 레벨 API(HLAPI)는 낮은 레벨 API를 레핑하고 일반 작업을 수행하기 위한 편리한 인터페이스를 제공한다.
• 낮은 레벨 API(LLAPI)는 더 많은 고급 사용자를 위해 최대한의 유연성을 제공한다.

 

PLUS

HLAPI 제공 기능
- HLAPI가 보일러플레이트 코드를 최소화하기 위해 설계

HTTP 서버에서 텍스트 또는 바이너리 데이터 가져오기(GET)
 - 표준 HTTP나 HTTPS 웹 서버에서 텍스트 데이터나 바이너리 데이터와 같은 간단한 데이터를 검색해서 가져오려면 UnityWebRequest.GET 호출을 사용해야 함
  - 데이터를 검색해서 가져오는 URL을 지정

HTTP 서버에서 텍스처 가져오기(GET)
 - 원격 서버에서 텍스처 파일을 검색해서 가져오기 위해 UnityWebRequest.Texture를 사용가능
 - 이 함수는 UnityWebRequest.GET과 매우 유사하지만 텍스처를 효율적으로 다운로드하고 저장하는 데 최적화 됨
 - 이 함수는 단일 문자열을 인수로 사용
 - 텍스처로 사용하기 위한 이미지 파일을 다운로드할 URL을 지정

HTTP 서버에서 에셋 번들 다운로드(GET)
 - 원격 서버에서 에셋 번들을 다운로드하기 위해 UnityWebRequest.GetAssetBundle을 사용 가능
 - 이 함수는 데이터를 내부 버퍼로 스트리밍하며, 워커 스레드에서 에셋 번들의 데이터를 디코드하고 압축을 푼다.
 - 다운로드된 데이터의 무결성을 확인하기 위해 검사 합계를 제공 가능
 - 가장 간단한 형태는 에셋 번들을 다운로드해야 하는 URL만 인수로 사용
 - 버전 번호나 Hash128 오브젝트를 인수로 제공하면 이 함수는 또한 이 인수를DownloadHandlerAssetBundle에 전달
그 다음, 다운로드 핸들러는 캐시 시스템을 활용

HTTP 서버로 양식 전송(POST)
- 양식 데이터를 지정하는 방식을 더 원활하게 조절하기 위해 UnityWebRequest 시스템에는 사용자가 구현 가능한 IMultipartFormSection 인터페이스가 포함
- 표준 애플리케이션의 경우 Unity는 데이터와 파일 섹션에 대한 디폴트 구현 MultipartFormDataSection 및 MultipartFormFileSection도 제공
- WWWForm POST 함수와 마찬가지로, 이 HLAPI 함수는 제공된 각 IMultipartFormSection을 순서대로 호출하여 RFC 2616에 지정된 표준 멀티파트 양식으로 포맷
- 미리 포맷된 양식 데이터는 표준 UploadHandlerRaw 오브젝트에 저장된 후 UnityWebRequest에 연결
그 결과 UnityWebRequest.POST 호출 후IMultipartFormSection 오브젝트의 변경 사항은 서버에 전송된 데이터에 반영되지 않음

HTTP 서버에 원시 데이터 업로드(PUT)
- 일부 최신 웹 애플리케이션은 HTTP PUT 동사를 통해 파일을 업로드하는 것을 선호
- 첫 번째 인수는 문자열이며, 요청에 타겟 URL을 지정
- 두 번째 인수는 문자열 또는 바이트 배열, 서버에 전송할 페이로드 데이터를 지정

고급 작업: LLAPI 사용
- 낮은 레벨 API(LLAPI)는 최대한의 유연성을 허용하기 위해 설계
일반적으로 LLAPI를 사용하려면 UnityWebRequest를 생성한 다음
적절한 DownloadHandler 또는 UploadHandler를 만들고 이를 UnityWebRequest에 첨부 필수

UnityWebRequest 생성
- WebRequest는 다른 오브젝트처럼 인스턴스화 가능
- 파라미터가 없는 스탠다드 생성자는 모든 설정이 비어있거나 기본값인 새 UnityWebRequest를 생성
- 타겟 URL이 설정되지 않고 커스텀 헤더가 설정되지 않고 리디렉션 한계가 32로 설정
- 두 번째 생성자는 문자열 인수를 취하고 UnityWebRequest의 타겟 URL을 문자열 인수의 값에 할당
- UnityWebRequest를 설정하고 상태를 추적하고 결과를 확인하는 데 사용할 수 있는 기타 여러 프로퍼티가 있음

UploadHandler 생성
 - 현재 한 가지 타입의 업로드 핸들러, UploadHandlerRaw만 사용
 - 이 클래스는 구성 시 데이터 버퍼를 받아들임
 - 이 버퍼는 내부적으로 네이티브 코드 메모리에 복사되며, 원격 서버가 바디 데이터를 받아들일 준비가 되면 UnityWebRequest 시스템에 의해 사용
 - 업로드 핸들러는 또한 Content Type 문자열을 받음.
이 문자열은 UnityWebRequest 자체에 Content-Type 헤더를 설정하지 않았을 경우 UnityWebRequest의 Content-Type 헤더의 값에 사용
 - UnityWebRequest에는 disposeUploadHandlerOnDispose 프로퍼티가 있으며, 디폴트 설정은 true
true일 경우 UnityWebRequest 오브젝트가 제거되면 연결된 업로드 핸들러가 이 오브젝트를 쓸모없게 만들 때 Dispose()도 호출
 - 업로드 핸들러에 대한 레퍼런스를 UnityWebRequest에 대한 레퍼런스보다 더 오래 보관하려면 disposeUploadHandlerOnDispose를 false로 설정 필수

DownloadHandler 생성
 - DownloadHandlerBuffer는 단순 데이터 스토리지로 사용
 - DownloadHandlerFile은 메모리를 적게 사용하면서 파일을 다운로드하고 디스크에 저장하는 데 사용
 - DownloadHandlerTexture는 이미지를 다운로드하는 데 사용
 - DownloadHandlerAssetBundle은 에셋 번들을 가져오는 데 사용
 - DownloadHandlerAudioClip은 오디오 파일을 다운로드하는 데 사용
 - DownloadHandlerMovieTexture는 비디오 파일을 다운로드하는 데 사용,
MovieTexture는 지원이 중단될 예정이므로 비디오를 다운로드하고 재생하려면 VideoPlayer를 사용하는 것이 좋음
 - DownloadHandlerScript는 특별한 클래스
자체적으로는 아무 역할도 하지 않지만, 이 클래스는 사용자가 정의한 클래스에 의해 상속 가능
 - 이 클래스는 UnityWebRequest 시스템에서 콜백을 수신 
이 콜백은 네트워크에서 도착한 데이터를 완전히 커스터마이즈하여 처리하는 데 사용 가능

 

 

지원되는 플랫폼

UnityWebRequest 시스템은 대부분의 Unity 플랫폼을 다음과 같이 지원

 

• 모든 버전의 에디터 및 스탠드얼론 플레이어
• WebGL
• 모바일 플랫폼 : iOS, Android
•  유니버셜 Windows 플랫폼

 

아키텍처

UnityWebRequest 생태계에서 HTTP 트랜잭션을 다음과 같이 세 단계의 작업으로 분리

• 서버에 데이터 제공
• 서버에 데이터 수신
• HTTP 플로우 컨트롤(예 : 리디렉트 및 오류 처리)

 

이러한 작업은 고급 사용자에게 더 나은 인터페이스를 제공하기 위해 다음과 같이 각각의 자체 오브젝트를 통해 관리된다.

• UploadHandler 오브젝트는 서버로의 데이터 송신을 담당
• DownloadHandler 오브젝트는 서버에서의 데이터 수신, 버퍼링 및 포스트 프로세스를 담당
• UnityWebRequest 오브젝트는 위의 두 오브젝트를 관리하고, HTTP 플로우 컨트롤을 담당
  이 오브젝트에서는 커스텀 헤더와 URL이 정의되며, 오류및 리디렉트 정보가 저장됨

 

모든 HTTP 트랜잭션의 일반 코드 플로우는 다음과 같음

 

• 웹 요청 오브젝트 생성
• 웹 요청 오브젝트 설정
  • 커스텀 헤더 설정
  • HTTP  동사 설정 (GET, POST, HEAD 등. 커스텀 동사는 Android용을 제외한 모든 플랫폼에서 사용 가능)
  • URL 설정
• (선택) 업로드 핸들러를 생성하여 웹 요청에 연결
  • 업도르할 데이터 제공
  • 업로드할 HTTP 양식 제공
• (선택) 다운로드 핸들러를 생성하여 웹 요청에 연결
• 웹 요청보내기
  • 코루틴 내에 있을 경우 Send() 호출 결과를 얻어서 요청이 완료될 때까지 대기 가능
• (선택) 다운로드 핸들러에서 수신한 데이터 읽기
• (선택) UnityWebRequest 오브젝트에서의 오류 정보, HTTP 상태 코드 및 리스폰스 헤더 읽기