HTTPS/HTTP 요청

Ren'Py는 renpy.fetch 함수로 HTTP·HTTPS를 통해 정보를 가져올 수 있습니다. 다음 기능을 제공합니다.

  • GET, POST, PUT 요청을 지원합니다.

  • POST나 PUT으로 데이터 또는 JSON을 서버에 전송할 수 있습니다.

  • 결과를 바이트, 문자열, JSON 객체로 받을 수 있습니다.

fetch는 게임 시작 후 Ren'Py의 메인 스레드에서 사용하도록 설계되었습니다. 데스크톱·모바일·웹에서 사용할 수 있습니다. 웹에서는 게임을 제공한 서버와 다른 서버에 요청할 경우 그 서버가 CORS를 지원해야 합니다.

다음은 서버에서 소식을 받아 오는 간단한 예제입니다.

$ news = renpy.fetch("https://example.com/news.txt", result="text")
"소식을 전해 드릴게요: [news]"

JSON을 서버로 보내고 JSON 응답을 받는 예제는 다음과 같습니다.

$ result = renpy.fetch("https://example.com/api", json={"name": "Ren'Py"}, result="json")

네트워크로 통신하는 다른 애플리케이션과 마찬가지로 renpy.fetch를 사용할 때도 보안을 고려해야 합니다. 특히 응답으로 받은 미디어를 표시할 때 주의하세요. Ren'Py는 일반적으로 악의적인 이미지·동영상·오디오 파일에 대한 방어를 보장하지 않습니다.

renpy.fetch(url, method=None, data=None, json=None, content_type=None, timeout=5, result='bytes', params=None, headers={})

지정한 URL에 HTTP 또는 HTTPS 요청을 보내고 응답 내용을 반환합니다. 실패하면 원인을 설명하는 텍스트와 함께 FetchError 예외를 발생시킵니다. 이 텍스트는 사용자에게 그대로 보여 주기에 적절하지 않을 수 있습니다.

url

요청할 URL입니다.

method

사용할 HTTP 메서드입니다. 보통 "GET", "POST", "PUT" 중 하나이지만 다른 메서드도 가능합니다. data나 json이 None이 아니면 기본값은 "POST"이고, 둘 다 None이면 GET입니다.

data

None이 아니면 요청에 함께 보낼 바이트 문자열입니다.

json

None이 아니면 요청에 함께 보낼 JSON 객체입니다. data보다 우선합니다.

content_type

전송 데이터의 콘텐츠 유형입니다. 생략하면 json이 None이 아닐 때는 "application/json", 그 외에는 "application/octet-stream"을 사용합니다. POST·PUT 요청에서만 사용합니다.

timeout

요청이 완료될 때까지 기다릴 최대 시간(초)입니다.

result

결과 처리 방식입니다. "bytes"이면 원시 바이트를 반환하고, "text"이면 UTF-8로 디코딩한 유니코드 문자열을 반환하며, "json"이면 JSON으로 디코딩합니다. 디코딩 중에는 다른 예외가 발생할 수도 있습니다.

params

URL의 쿼리 문자열에 추가할 매개변수 딕셔너리입니다.

headers

요청에 포함할 헤더 딕셔너리입니다.

상호작용 안팎에서 모두 호출할 수 있습니다.

  • 상호작용 바깥에서는 timeout까지 기다리는 동안 renpy.pause()를 반복 호출해 Ren'Py가 멈추지 않게 합니다. 플레이어에게 진행 상황을 알려 주는 스크린을 표시하는 것도 좋습니다.

  • 액션 안처럼 상호작용 도중 호출하면 요청이 끝나거나 시간 초과가 될 때까지 화면 처리를 차단합니다. 오디오 처리는 계속 시도하므로 소리는 재생됩니다.

모든 플랫폼에서 작동하도록 설계되었습니다. 다만 웹에서는 게임과 다른 출처로 보내는 요청이 CORS로 허용되지 않으면 실패합니다.

Requests 라이브러리

데스크톱과 모바일에는 Requests 라이브러리도 포함되어 있습니다. 기능은 더 풍부하지만 renpy.fetch만큼 Ren'Py와 긴밀하게 통합되지는 않습니다. 예를 들어 renpy.fetch는 데이터를 기다리는 동안 renpy.pause()를 호출하지만 Requests는 실행을 차단하므로, 오디오가 멈추는 등의 문제가 생길 수 있습니다.