WebRPCs
WebRPC는 외부 서비스를 Photon 서버로 통합하는 유연한 방식 입니다.
예를 들면 WebRPC로 Photon 클라이언트들은 외부 웹서비스에서 데이터를 가져오도록 요청 할 수 있습니다.
웹 서비스 기본
WebRPC 아키텍처는 간단 합니다.
Photon 서버는 클라이언트와 웹서버 사이에서 Proxy 또는 Relay 역할을 합니다.
WebRPC webhook의 확장 또는 커스텀 클라이언트-주도 webhook의 형태가 될 수 있습니다.
다음의 개발 팁을 고려 해 보시기 바랍니다:
- 언어, 프레임워크, 웹서버 종류에 관계없이 WebRPC에 대한 서비스를 구현 할 수 있습니다.
- 모든 경우에 있어서 전송하는 데이터를 최소화하여 플레이어가 데이터의 부담을 느끼지 않도록 해야 합니다.
환경구성
Photon 서버에서는 WebRPC 환경구성은 로드밸런싱 서버인 마스터서버와 게임서버 모두 app.config
(또는 Photon.LoadBalancingClient.dll.config
) 파일에 설정 할 수 있습니다
BaseURL
값이 필요하며 사용불가로 할 수 있습니다. 아래는 환경구성의 예 입니다:
XML
<WebRpcSettings Enabled="true">
<BaseUrl Value="https://example.com/WebRPC" />
</WebRpcSettings>
요청(Request)
클라이언트 측에서 Photon WebRPC는 마스터 또는 게임서버에 접속 후 실행 할 수 있는 Photon 오퍼레이션 입니다.
URL 경로 (WebRPC 메소드 명으로 알려짐)가 필요하고 추가적인 두 번째 아규먼트에는 웹 서비스에게 전송되는 데이터가 포함되어 있습니다(WebRPC 파라미터로 알려져 있음).
이 두개의 아규먼트들은 LoadBalancingClient.OpWebRpc
메소드에 전달 될 수 있습니다.
UriPath
는 WebRPC의 상대 경로로 원격 프로시져 이름과 일치해야 합니다.
URL 자체에 파라미터를 전달 하는 것도 가능 합니다.
이 경우에 query string 안의 상대 경로에 프로시져 이름이 추가되어 있어야 합니다.
Photon 서버가 요청을 받을 때 프로시져 이름은 동일 URL의 웹 서비스에게 포워딩 되기전에 BaseURL에 합쳐져서 WebRPC URL의 절대 경로로 만들어지게 됩니다.
HTTP 요청 메소드는 POST로 사용되기 때문에 클라이언트가 전송한 파라미터가 있으면 Photon은 4개의 기본 프로퍼티와 같이 JSON POST 데이터로 전달합니다:
AppVersion
:
게임클라이언트에서 설정된 어플리케이션의 버전.UserId
:
WebRPC를 작성한 액터 ID.
클라이언트가 전송한 다른 프로퍼티는 파라미터의 일부에 있습니다.
클라이언트에서 사용된 WebRpcParameters
타입이 Dictionary<string, object>
이면 모든 키/값 쌍은 post 데이터 객체의 루트내에서 전송 됩니다.
이외에 JSON 유효 타입인 경우에 새로운 프로퍼티인 RpcParams
의 값으로 포함되게 될 것 입니다.
예제 1
BaseURL 이 https://my.service.org/
이고 클라이언트가 WebRPC("method?id=1", parameters)
를 호출 합니다.
파라미터들은 Dictionary<string, object>
타입이며 내용은 {"key1": 1, "key2": "yx", "key3": true}
입니다.
이 경우에 Photon은 https://my.service.org/method?id=1
을 호출 하고 추가적인 JSON을 POST 합니다.
JavaScript
{
"AppId": "00000000-0000-0000-0000-000000000000",
"AppVersion": "client-x.y.z",
"Region": "EU",
"UserId": "userXYZ",
"key1": 1,
"key2": "yx",
"key3": true
}
예제 2
BaseURL은 https://my.service.org/
이고 클라이언트가 WebRPC("method?id=1", parameters)
를 호출 합니다.
파라미터들은 객체들의 배열 입니다:object[] { 0, "xy", false }
.
이 경우에 Photon은 https://my.service.org/method?id=1
호출 하고 추가적으로 JSON을 POST 합니다:
JavaScript
{
"AppId": "00000000-0000-0000-0000-000000000000",
"AppVersion": "client-x.y.z",
"Region": "EU",
"UserId": "userXYZ",
"RpcParams": [0, "xy", false]
}
예제 3
BaseURL은 https://my.service.org/
이고 클라이언트가 WebRPC("method?id=1", parameters)
를 호출 합니다.
파라미터들은 단순한 원시 타입입니다. 문자열을 "test"라고 가정해 봅시다.
이 경우에 Photon은 https://my.service.org/method?id=1
호출 하고 추가적인 JSON을 POST 합니다:
JavaScript
{
"AppId": "00000000-0000-0000-0000-000000000000",
"AppVersion": "client-x.y.z",
"Region": "EU",
"UserId": "userXYZ",
"RpcParams": "test"
}
데이터의 안전한 전송
WebRPC는 암호화된 객체 AuthCookie
를 사용 할 수 있는 경우 웹 서비스로 안전하게 전송 할 수 있는 옵션을 제공 합니다.
클라이언트 코드에서 WebRPC 오퍼레이션 메소드를 호출 할 때 웹 플래그 (SendAuthCookie = 0x02
)를 설정하여 수행 될 수 있습니다.
커스텀 인증 프로바이더로 부터 인증을 성공 한 후에 AuthCookie
를 얻을 수 있습니다.
상세한 정보는 커스텀 인증 문서 페이지를 참고 하시기 바랍니다.
응답(Response)
WebRPC의 웹서비스는 Photon이 클라이언트에게 결과를 전송 할 수 있도록 JSON 객체에 응답 해야 합니다.
응답에는 ResultCode
, Data
와 선택적으로 Message
가 포함되어 있어야 합니다.
ResultCode
는 정상적인 경우 0이 되어야 하며 다른 값은 오류에 대한 코드 입니다.
이 코드를 통해 클라이언트가 오류에 대한 처리를 할 수 있도록 하고 읽을 수 있는 메시지를 추가하는 것이 가장 좋은 방식 입니다.
Data
는 비어 있을 수 있으나 아무 것이라도 보낼 수 있으며 반드시 올바른 JSON 형식이어야 합니다.
모든 Photon 오퍼레이션과 같이 WebRPC의 OperationResponse
에는 ReturnCode
가 있습니다.
만약 오퍼레이션이 성공했다면 ErrorCode.Ok (0)
값을 가지고 있을 것 입니다.
오류가 발생했으면 ErrorCode.ExternalHttpCallFailed (32744)
가 표시 될 것 입니다.
에러의 경우 추가적인 정보는 OperationResponse.DebugMessage
를 검토하여 볼 수 있습니다.
대부분의 클라이언트 SDK에는 WebRPC 결과를 해석 해주는 helper 클래스인 WebRpcResponse
가 포함되어 있습니다.
WebRpcResponse
는 오퍼레이션 응답 파라미터에 있는 다음의 키로 부터 값을 가져와 웹 서비스의 리턴되는 결과 코드, 데이터와 추가적인 메시지를 작성 할 것 입니다.
ParameterCode.WebRpcReturnCode (207)
웹 서비스가 리턴 해준ResultCode
값을 가지고 있습니다.ParameterCode.WebRpcReturnMessage (206)
웹 서버가 리턴한 이벤트 메시지를 담고 있습니다.ParameterCode.WebRpcParameters (208)
웹 서버가 리턴한 데이터를 담고 있습니다.
웹 서버로부터 전송된 데이터의 타입에 따라 예상되는 타입은 다르지만 유효한 JSON 이어야만 합니다.
WebRPC를 선택하는 이유
HTTP 요청을 전송하는 것은 Photon 없이 수행 할 수 있습니다.
스스로 HTTP 클라이언트를 작성하거나 SDK 또는 라이브러리에서 사용 할 수 있는 것을 사용하면 됩니다.
하지만 Photon WebRPC는 더 많은 것을 제공하고 있습니다.
몇 가지 잇점을 나열해 보겠습니다:
모든 로직을 하나의 연결된 클라이언트로 보관하고 "라이프사이클"과 "상태 머신"을 처리하는 것이 더 좋습니다. Photon 클라이언트는 이러한 경우 필요한 것 입니다.
WebRPC 오퍼레이션은 JSON 양방향 직렬화를 해 줍니다.
AuthCookie
사용하거나 서버와 서버간에 더 민감한 데이터 교환시에 클라이언트 식별에 대하여 검증 할 수 있습니다. 이 기능에 대한 사용방법은 여기를 읽어 주시기 바랍니다..
GetGameList
GetGameList
에 대한 예제를 설명합니다. GitHub 페이지에서 제공하고 있는 샘플 중의 하나를 활용 하려면 원격 프로시져 이름의 철자에 주의 해야 합니다. 여기에는 's' 가 포함되어 있지 않습니다 :
한편 WebRPC 구현에서는 편한대로 이름을 선택 할 수 있습니다.
GetGameList
는 특별한 WebRPC 로서 "메모리 데모"에서 Photon 의 WebRPC 기능을 설명할 때 처음 소개되었습니다.
대부분의 게임에서 이전에 저장되었던 게임들을 가져올 필요가 있기 때문에 더 특별 합니다.
웹 서비스에 게임의 목록을 가져 오는 요청을 보낸 후 게임에 다시 참여하고 플레이를 계속한다는 것은 기본적인 사상 입니다.
이렇게 하기 위해서는 대시보드 에서 어플리케이션이 올바르게 설정 되었다는 것을 가정 하고 있습니다:BaseUrl
은 반드시 웹서비스 위치를 가리켜야 하고 게임 데이터를 보존 하기 위하여 IsPersistent
가 true
로 설정 되어 있어야 하며 GameClose webhook 이 활성화 되어 있어야 합니다.
GameClose Webhook 은 게임데이터로써 매우 중요한데 Photon의 직렬화된 룸 State
에 따라 웹 서비스에 의해 GameClose Webhook 이 리턴 되어야 합니다.
웹 서비스는 저장된 게임 데이터에 접근 할 수 있어야 하며 HTTP POST 요청을 수신, 처리 하여 WebRPC 의 패스(여기에서는GetGameList
)로 전송 할 수 있도록 준비가 되어야 합니다.
Photon 은 모든 WebRPC 요청 데이터에 UserId
를 전송하기 때문에 커스텀 파라미터를 추가할 필요는 없습니다.
Request는 아무런 아규먼트 없이 전송됩니다.
웹 서비스는 JSON 객체로 Data
에 저장된 게임의 목록을 리턴 해야 합니다. 저장된 게임들의 GameId 가 키가 됩니다.
각 값은 JSON 객체로 두개의 프로퍼티로 구성되어 있습니다:
ActorNr
: WebRPC 를 호출하는 액터의 원시 ActorNr 와 동일 하며 이 ActorNr 는 처음에 해당 룸에 참여 할 때 부여 받은 것 입니다. ActorNr 는 저장할 때 의도적으로 분리하여 저장한 경우에 쉽게 로드될 수 있으며 각 룸의 저장된State
객체를 ActorList 와 UserId를 비교하는 루프를 돌아 얻을 수 있습니다.Properties
: CustomRoomProperties의 키:값 쌍으로 로비에서 볼 수 있고 각각의 룸의 저장된State
안에 포함되어 있는CustomProperties
프로퍼티로 부터 얻을 수 있습니다.
JavaScript
{
"ResultCode":0,
"Message":"",
"Data":{
"RoomA":{
"ActorNr":3,
"Properties":{
"Map":"USA",
"Mode":"FFA",
"Respawn":true
}
},
"RoomB":{
"ActorNr":5,
"Properties":{
"Map":"Germany",
"Mode":"TDM",
"TeamA":1,
"TeamB":5
}
},
"RoomC":{
"ActorNr":1,
"Properties":{
"Map":"Russia",
"Mode":"CTF",
"TeamA":1,
"TeamB":5,
"Flag":20
}
}
}
}
마스터와 게임서버에서 WebRPC 호출이 허용되어 있을 지라도 룸에 참여하기 전에 GetGameList
를 호출 하는 것이 적절합니다. 즉, 마스터 서버에서 호출하는 것입니다.
웹 서비스로 데이터 전달 하기
WebRPC 는 클라이언트에서 웹 서비스로 데이터를 전달하는 3가지 방식을 지원 합니다.
3가지 타입은 독립적으로 사용하거나 조합하여 사용할 수 있습니다.
예를들면 GetGameList
를 확장하여 저장된 게임 목록을 특정 상대를 기반으로 필터 한 후 얻고 싶을 때 세가지 다른 방식을 사용할 수 있습니다.
RESTful 방식:
상대 URI:
/GetGameList/{opponentId}
POST data:
상대 URI:
/GetGameList
Request data:
Plain Old Text
{ "AppId": "00000000-0000-0000-0000-000000000000", "AppVersion": "client-x.y.z", "Region": "EU", "UserId": "userXYZ", "OpponentId": "opponentId" }
Query string (GET 파리미터로 알려져 있음):
상대 URI:
/GetGameList?opponentId={opponentId}
물론 웹 서비스는 선택된 메소드에 따라 업데이트 되어야 합니다.
데이터 타입 변환
이 섹션에서는 Photon 서버와 웹 서비스간의 데이터 교환의 타입에 대해서만 설명합니다.
클라이언트와 Photon 서버간의 데이터 타입에 대해서는 Photon 의 직렬화 페이지를 참고 하시기 바랍니다.
Photon 서버 -> 웹 서비스
C# / .NET (Photon 지원 타입) | JavaScript / JSON |
---|---|
byte
|
number |
short
|
|
int
|
|
long
|
|
double
|
|
bool
|
bool |
string
|
string |
byte[] (byte 배열 length < short.MaxValue )
|
string (Base64 encoded) |
T[] (array of supported type T, length < short.MaxValue )
|
array |
Hashtable (of supported types, count < short.MaxValue , preferably Photon implementation)
|
object |
Dictionary (keys and values of supported types, count < short.MaxValue )
|
object |
null
|
null
|
샘플 요청 데이터 (타입들이 연결되어 있습니다)
Photon 서버 전송:
JavaScript
{
"(Dictionary<String,Object>)Dictionary":{
"(Int32)dk_int":"1",
"(String)dk_str":"dv2",
"(Boolean)dk_bool":"True"
},
"(Hashtable)Hashtable":{
"(Byte)hk_byte":"255",
"(Object[])hk_array":[
"(Object)0",
"(Object)xy",
"(Object)False"
],
"hk_null":"null"
},
"null":"null",
"(String[])string[]":[
"(String)PUN",
"(String)TB",
"(String)RT",
"(String)Bolt",
"(String)Chat"
],
"(Byte[])byte[]":[
"(Byte)255",
"(Byte)0"
],
"(Int16[])short[]":[
"(Int16)-32768",
"(Int16)32767"
],
"(Int32[])int[]":[
"(Int32)-2147483648",
"(Int32)2147483647"
],
"(Int64[])long[]":[
"(Int64)-9223372036854775808",
"(Int64)9223372036854775807"
],
"(Single[])float[]":[
"(Single)-3.402823E+38",
"(Single)3.402823E+38"
],
"(Double[])double[]":[
"(Double)-1.79769313486232E+308",
"(Double)1.79769313486232E+308"
],
"(Boolean[])bool[]":[
"(Boolean)True",
"(Boolean)False"
]
}
Web 서비스 수신:
JavaScript
{
"(object)Dictionary":{
"dk_int":"(number)1",
"dk_str":"(string)dv2",
"dk_bool":"(boolean)true"
},
"(object)Hashtable":{
"hk_byte":"(number)255",
"hk_null":null,
"hk_array":[
"(number)0",
"(string)xy",
"(boolean)false"
]
},
"null":null,
"(array)string[]":[
"(string)PUN",
"(string)TB",
"(string)RT",
"(string)Bolt",
"(string)Chat"
],
"byte[]":"(string)/wA=",
"(array)short[]":[
"(number)-32768",
"(number)32767"
],
"(array)int[]":[
"(number)-2147483648",
"(number)2147483647"
],
"(array)long[]":[
"(number)-9223372036854776000",
"(number)9223372036854776000"
],
"(array)float[]":[
"(number)-3.40282347e+38",
"(number)3.40282347e+38"
],
"(array)double[]":[
"(number)-1.7976931348623157e+308",
"(number)1.7976931348623157e+308"
],
"(array)bool[]":[
"(boolean)true",
"(boolean)false"
]
}
웹 서비스 -> Photon 서버
C#/.Net 에서 JavaScript/JSON 타입과 각각 대응하는 테이블입니다.
Here is a table that matches each JavaScript/JSON type to its equivalent one in C#/.Net :
JavaScript / JSON | C# / .Net |
---|---|
object |
Dictionary
|
array |
object[] (array of objects)
|
number (integral) |
long
|
number (floating) |
double
|
string |
string
|
boolean |
bool
|
null (not a type)
|
null
|
undefined (when sent)
|
null
|
응답 데이터 샘플 (타입들이 연결되어 있습니다)
Web Service 전송:
JavaScript
{
"(object)number": {
"MAX_VALUE": "(number)1.7976931348623157e+308",
"MIN_VALUE": "(number)5e-324"
},
"(object)object": {
"string": "(string)xyz",
"null": null,
"bool": "(boolean)false",
"undefined": "(undefined)undefined",
"number": "(number)-3.14"
},
"(array)array": [
"(string)xyz",
"(number)0",
"(boolean)true",
null,
"(undefined)undefined"
]
}
Photon Server 수신:
JavaScript
{
"(Dictionary<String,Object>)number":{
"(Double)MAX_VALUE":"1.79769313486232E+308",
"(Double)MIN_VALUE":"4.94065645841247E-324"
},
"(Dictionary<String,Object>)object":{
"(String)string":"xyz",
"null":"null",
"(Boolean)bool":"False",
"(Double)number":"-3.14"
},
"(Object[])array":[
"(Object)xyz",
"(Object)0",
"(Object)True",
"null",
"null"
]
}