Multiplay 서버에서 HTTP 요청하기

zepeto 월드 멀티플레이 서버에서 zepeto multiplay httpservice 모듈을 사용하여 http 요청을 할 수 있습니다 비즈니스 로직 작업, 데이터 저장, 통계 분석, 오류 추적 등을 위해 외부 웹 서비스를 통합하세요 https 프로토콜만 사용되도록 하세요 http는 개발 환경에서만 지원됩니다 요청은 포트 80과 443에서만 허용됩니다 요청 및 응답 본문의 최대 크기는 16kb로 제한됩니다 과도한 요청이 발생할 경우 월드 서비스에 대한 잠재적 제한을 피하기 위해 분당 요청 수를 500 이하로 유지하세요 외부 웹 서비스가 5초 이내에 응답하지 않으면 요청이 실패합니다 응답 헤더의 content type이 httpcontenttype 열거형에 정의된 값과 일치하는지 확인하세요 그렇지 않으면 요청이 실패합니다 다양한 이유로 웹 요청이 실패할 가능성이 있으므로 방어적으로 코딩하는 것이 좋습니다 zepeto multiplay httpservice 📘 다음 가이드를 참조하세요 \[ zepeto multiplay httpservice api https //developer zepeto me/docs/multiplay server/interfaces/zepeto multiplay httpservice httpservice ] 메서드 방법 설명 httpservice getasync(url string, headers? httpheader) promise 비동기적으로 http get 요청을 수행합니다 \[매개변수] url 요청을 보낼 웹 주소입니다 headers http 요청 헤더입니다 (선택 사항) \[반환 값] promise\<httpresponse> 응답에 대한 정보를 포함하는 httpresponse 객체를 promise로 반환합니다 httpservice postasync(url string, body httpbodytype, headers? httpheader) promise 비동기적으로 http post 요청을 수행합니다 \[매개변수] url 요청을 보낼 웹 주소입니다 body 요청 본문 내용입니다 headers http 요청 헤더입니다 (선택 사항) \[반환 값] promise\<httpresponse> 응답에 대한 정보를 포함하는 httpresponse 객체를 promise로 반환합니다 httpservice postasync(url string, body httpbodytype, httpcontenttype httpcontenttype, headers? httpheader) promise 비동기적으로 http post 요청을 수행합니다 \[매개변수] url 요청을 보낼 웹 주소입니다 body 요청 본문 내용입니다 httpcontenttype 요청 content type 헤더를 지정합니다 headers http 요청 헤더입니다 (선택 사항) \[반환 값] promise\<httpresponse> 응답에 대한 정보를 포함하는 httpresponse 객체를 promise로 반환합니다 이 서명을 사용할 때, headers에 'content type'을 추가하면 httpcontenttype에 지정된 내용으로 덮어씌워집니다 기타 선언 선언 설명 httpcontenttype http 헤더의 content type을 지정하는 상수의 열거형입니다 applicationjson 'application/json' applicationxml 'application/xml' applicationurlencoded 'application/x www form urlencoded' textplain 'text/plain' textxml 'text/xml' httpbodytype http 요청 본문 콘텐츠의 유형으로, 문자열 또는 문자열 키와 임의의 값을 가진 객체일 수 있습니다 httpheader http 요청 헤더를 정의하는 유형으로, 속성 값은 객체 내에서 문자열 또는 숫자일 수 있습니다 httpresponse http 요청 결과 및 응답 데이터에 대한 정보를 포함하는 인터페이스입니다 statuscodehttp 응답의 상태 코드를 나타내는 숫자입니다 일반적으로 200은 성공적인 요청을 나타냅니다 statustexthttp 응답의 상태 메시지를 나타내는 문자열입니다 일반적으로 "ok"는 성공적인 요청을 나타냅니다 response http 응답 본문 데이터가 포함된 문자열입니다 📘 http 상태 https //developer mozilla org/en us/docs/web/http/status https //developer mozilla org/en us/docs/web/http/status 코드 샘플 기본 get 요청 간단한 get 요청 예제를 만들어 보겠습니다 httpservice getasync 새로운 클라이언트가 멀티플레이 룸에 연결되면, 외부 웹 서비스에 http 요청을 보내고 결과를 기록합니다 restcountries com https //restcountries com/ 는 다양한 국가에 대한 정보를 제공하는 오픈 api입니다 우리는 이 서비스를 사용하여 일본의 수도를 알아낼 것입니다 multiplay를 설정한 후, world multiplay/index ts를 열고 서버 스크립트를 다음과 같이 작성하세요 📘 다음 가이드를 참조하세요 \[ 멀티플레이 docid\ lqdlv5a9ek5hwd16tv0y ] import { sandbox, sandboxoptions, sandboxplayer } from "zepeto multiplay"; import { httpservice } from "zepeto multiplay httpservice"; export default class extends sandbox { oncreate(options sandboxoptions) { } onjoin(client sandboxplayer) { this findcapitalcity() } onleave(client sandboxplayer, consented? boolean) { } findcapitalcity() { // make the request to the restcountries api httpservice getasync("https //restcountries com/v3 1/name/japan?fields=capital") // handler for the http response then((httpresponse) => { // parse the json response data from the api (which is nested in http response) let countries = json parse(httpresponse response); console log("the capital city of japan is "); console log(`${countries\[0] capital}`); }); } } 코드 설명 클라이언트가 멀티플레이 룸에 연결되면, onjoin 함수가 트리거되고, findcapitalcity 만약 getasync 호출이 restcountries api에 성공하면, httpresponse 객체에 접근할 수 있습니다 then 콜백에서 api 응답을 json 형식에서 객체로 변환하기 위해 httpresponse response 를 파싱합니다 api 응답의 구조를 참조하여 원하는 속성에 접근하고 그 값을 출력합니다 unity editor에서 멀티플레이 서버를 실행하고 장면을 재생하면, 콘솔에 다음과 같은 내용이 표시됩니다 일본의 수도는 도쿄 방어적 코딩 관행 한편, 서론의 주의 사항에서 언급했듯이, 웹 요청은 웹 주소나 api 응답 형식의 변경 등 다양한 이유로 실패할 수 있습니다 이러한 요청을 적절히 처리하지 않으면 월드 플레이에 다양한 부정적인 영향을 미칠 수 있으므로, 특히 http 요청을 처리할 때 방어적으로 코딩하는 것이 권장됩니다 다음은 위의 코드에 여러 방어적 코딩 기법을 적용한 예입니다 findcapitalcity() { // restcountries api에 요청을 보냅니다 httpservice getasync( "https //restcountries com/v3 1/name/japan?fields=capital", { 'accept' httpcontenttype applicationjson }) // http 응답 핸들러 then((httpresponse) => { // api 호출이 200(ok)을 반환했는지 확인합니다 if (httpresponse statuscode != 200) { // 200(ok)이 아니면 진행하지 않고 사용자 정의 오류를 발생시킵니다 throw (`api 오류 ${httpresponse statuscode} ${httpresponse statustext}`); } // api로부터 json 응답 데이터를 반환합니다 return httpresponse response; }) // api로부터 json 응답 데이터 핸들러 then((response) => { // json 응답 데이터를 파싱합니다 let countries = json parse(response); // api 응답 데이터가 유효한지 확인합니다 if (!array isarray(countries) || !countries length) { // 배열이 아니거나 비어있으면 // 진행하지 않고 사용자 정의 오류를 발생시킵니다 throw (`api 오류 응답 데이터가 유효하지 않습니다 `); } let country = countries\[0]; // 'capital' 필드가 유효한지 확인합니다 if (!country capital) { // 'capital' 필드가 존재하지 않거나 비어있으면 // 진행하지 않고 사용자 정의 오류를 발생시킵니다 throw (`api 오류 'capital' 필드가 유효하지 않습니다 `); } console log("일본의 수도는 ") console log(`${country capital}`); }) // getasync 호출 및 'then' 절에서 발생하는 오류 핸들러 catch((reason) => { console log("api 요청 오류"); console log(reason); }); } 여기 적용된 방어적 코딩 기술은 다음과 같습니다 다음 사용 accept 헤더 accept 헤더는 응답 본문의 예상 content type을 지정하는 데 사용됩니다 서버에 따라 응답 content type은 accept 헤더에 따라 조정될 수 있습니다 확인 httpresponse statuscode httpresponse statuscode 속성은 요청의 성공 여부를 확인하는 데 사용됩니다 json 데이터 구조 검증 json parse 로 구문 분석된 객체의 데이터 구조가 예상 구조와 일치하는지 확인합니다 속성 존재 확인 사용하려는 속성이 실제로 객체에 존재하는지 확인합니다 promise의 사용 catch 메서드 promise의 catch 메서드는 api 요청 및 응답 처리 중 발생할 수 있는 오류를 처리하는 데 사용됩니다 이 기술들은 예기치 않은 오류에 직면했을 때 코드가 신뢰성 있게 작동하도록 보호하여 강력함을 향상시킵니다 클라이언트와의 통합을 위한 룸 메시지 http 요청은 멀티플레이 서버에서만 가능합니다 그러나 멀티플레이 룸 메시지를 사용하면 클라이언트에서 서버를 트리거하여 외부 웹 서비스에 http 요청을 보내고 클라이언트 내에서 응답을 활용할 수 있습니다 다음 예제는 클라이언트 서버 통합을 보여줍니다 이 시연에서는 클라이언트의 ui에서 버튼을 누르면 버튼에 해당하는 국가의 수도가 표시됩니다 📘 다음 가이드를 참조하십시오 \[ multiplay room message docid\ yt8t8xpljhscnor5y4r7n ] 클라이언트 코드 import { zepetoscriptbehaviour } from 'zepeto script' import { room } from 'zepeto multiplay' import { zepetoworldmultiplay } from 'zepeto world'; import { button, text } from 'unityengine ui' export default class samplescript extends zepetoscriptbehaviour { public multiplay zepetoworldmultiplay; public room room; public countrybuttons button\[]; public capitaltext text; start() { interface response { capitals string\[] } for (const countrybutton of this countrybuttons) { countrybutton onclick addlistener(() => { if (this room !== null) { // send the country name as a 'client to server' type message to the server this room send("client to server", countrybutton getcomponentinchildren\<text>() text); } }); }; this multiplay roomcreated += (room room) => { this room = room; // handle messages received with a 'server to client' type this room addmessagehandler("server to client", (message response) => { // for countries with multiple capital cities, // join the string elements with ', ' and display on the scene this capitaltext text = message capitals join(", "); }); }; } } 코드 설명 우리는 국가 이름을 표시하는 버튼을 반복하는 리스너를 정의합니다 클릭하면 이 리스너는 멀티플레이 서버에 방 메시지를 보냅니다 이 리스너는 버튼에 표시된 국가 이름을 '클라이언트 서버' 유형 메시지로 보냅니다 응답을 처리하기 위해, 우리는 '서버 클라이언트' 유형으로 수신된 방 메시지를 처리하는 리스너도 정의합니다 이 리스너는 서버에서 수신한 수도 이름을 화면에 표시합니다 여러 수도가 있는 경우, 화면에 쉼표로 구분하여 표시됩니다 서버 코드 import { sandbox, sandboxoptions, sandboxplayer } from "zepeto multiplay"; import { httpservice } from "zepeto multiplay httpservice"; export default class extends sandbox { oncreate(options sandboxoptions) { // 'client to server' 유형의 메시지를 처리합니다 this onmessage("client to server", (client, message) => { console log(`클라이언트 ${client userid}가 요청을 보냈습니다 메시지 ${message}`); this findcapitalcity(message, client); }); } onjoin(client sandboxplayer) { } onleave(client sandboxplayer, consented? boolean) { } findcapitalcity(countryname string, client sandboxplayer) { // countryname을 경로 매개변수로 사용하여 api 요청 // countryname은 클라이언트가 방 메시지로 보냅니다 httpservice getasync(`https //restcountries com/v3 1/name/${countryname}?fields=capital`) then((httpresponse) => { if (httpresponse statuscode != 200) { throw (`api 오류 ${httpresponse statuscode} ${httpresponse statustext}`); } return httpresponse response; }) then((response) => { let countries = json parse(response); if (!array isarray(countries) || !countries length) { throw (`api 오류 응답 데이터가 유효하지 않습니다 `); } let country = countries\[0]; if (!country capital) { throw (`api 오류 'capital' 필드가 유효하지 않습니다 `); } // 클라이언트에게 'server to client' 유형의 메시지를 보냅니다 // 메시지는 수도 이름을 포함하는 객체입니다 client send("server to client", { "capitals" country capital }); }) catch((reason) => { console log("api 요청 오류"); console log(reason); }); } } 코드 설명 우리는 '클라이언트 서버' 유형의 멀티플레이 룸 메시지를 수신하면 호출하는 리스너를 정의합니다 findcapitalcity 우리는 국가 이름을 사용하여 멀티플레이 룸 메시지의 주소를 구성하고 getasync 호출을 합니다 만약 getasync 호출이 성공하면, 응답은 이전 예제와 같이 처리됩니다 restcountries api의 응답에서 얻은 수도 이름은 '서버 클라이언트' 유형의 룸 메시지로 클라이언트에 전송됩니다 post 요청 마지막으로, httpservice postasync 를 사용하여 post 요청 예제를 만들어 보겠습니다 postman echo https //postman echo com/ 는 웹 요청에서 수신된 내용을 보여주는 구조화된 응답을 제공하는 서비스로, 클라이언트가 요청을 올바르게 구성했는지 확인하는 데 효과적입니다 이 예제를 통해 쿼리 매개변수, 요청 본문 및 헤더가 포함된 post 요청을 설정하고 요청이 올바르게 구성되었는지 확인할 것입니다 multiplay를 설정한 다음, world multiplay/index ts를 열고 서버 스크립트를 다음과 같이 작성하세요 import { sandbox, sandboxoptions, sandboxplayer } from "zepeto multiplay"; import { httpcontenttype, httpservice } from "zepeto multiplay httpservice"; export default class extends sandbox { oncreate(options sandboxoptions) { } onjoin(client sandboxplayer) { this echopost() } onleave(client sandboxplayer, consented? boolean) { } echopost() { httpservice postasync( // api 엔드포인트와 쿼리 매개변수 "https //postman echo com/post?argkey=argvalue", // json 요청 본문 { "datakey" "datavalue" }, // 요청 콘텐츠 유형 httpcontenttype applicationjson, // http 헤더 { "header key" "header value" }) then((httpresponse) => { if (httpresponse statuscode != 200) { throw (`api 오류 ${httpresponse statuscode} ${httpresponse statustext}`); } return httpresponse response; }) then((response) => { let parsed = json parse(response); console log(`쿼리 매개변수 argkey ${parsed args argkey}`); console log(`요청 본문 datakey ${parsed data datakey}`); console log(`요청 헤더 header key ${parsed headers\["header key"]}`) }) catch((reason) => { console log("api 요청 오류"); console log(reason); }); } } 코드 설명 클라이언트가 멀티플레이 룸에 연결될 때, echopost 함수가 onjoin 트리거에서 호출됩니다 postasync 요청을 만들 때 첫 번째 매개변수에서 쿼리 매개변수를 포함한 url 문자열을 구성합니다 두 번째 매개변수에서 요청 본문 내용을 설정합니다 네 번째 매개변수에서 요청 헤더를 구성합니다 요청 본문이 json 형식임을 지정하기 위해 세 번째 매개변수에 'application/json' content type을 설정합니다 만약 postasync 호출이 성공하면, 우리는 httpresponse 객체에 접근할 수 있습니다 그 후 콜백에서 우리는 httpresponse response 를 파싱하여 api 응답을 json 형식에서 객체로 변환합니다 api 응답의 구조를 참조하여, 우리는 콘솔 출력을 사용하여 http 요청의 쿼리 매개변수, 요청 본문 및 요청 헤더가 올바르게 구성되었는지 확인합니다 unity 에디터에서 멀티플레이 서버를 실행하고 장면을 재생하면 콘솔에 다음과 같은 내용이 표시됩니다 쿼리 매개변수 argkey\ argvalue 요청 본문 datakey\ datavalue 요청 헤더 header key\ header value