WebRPC
WebRPCを使用すれば、Photon serverに柔軟に外部サービスを統合することができます。 たとえば、WebRPCによってPhotonクライアントが外部Webサービスからデータをフェッチするようサーバーにリクエストすることができます。
目次
Webサービスの基礎
Photon Serverは、クライアントとWebサーバー間で プロキシ または リレー の役割を果たします。 WebRPCはWebhookの拡張、またはクライアント主導のWebhookと考えることができます。
開発の際には、以下のヒントを参照してください:
- WebRPCにサービスを実装するには、あらゆる言語、フレームワーク、Webサーバーを使用することができます。
- すべての場合において、送信するデータは最小化し、プレイヤーへの負荷を抑えてください。
設定
Photon Serverでは、以下でWebRPC設定をおこなうことができます:
- マスターサーバー向けには "deploy\Loadbalancing\Master\bin\Photon.LoadBalancing.dll.config"
- ゲームサーバー向けには"deploy\Loadbalancing\GameServer\bin\Photon.LoadBalancing.dll.config"
これにはBaseURL
値が必要で、無効化することができます。設定例は以下のとおりです:
<WebRpcSettings Enabled="true">
<BaseUrl Value="https://example.com/WebRPC" />
</WebRpcSettings>
リクエスト
Photon WebRPCはマスターサーバーまたはゲームサーバーに接続した際に、クライアント側から許可されるPhotonオペレーションです。 Photon WebRPCにはURIパス文字列(別名:WebRPCメソッド名)が必要です。また、オプションでWebサービスに送信されるデータを含む2番目の引数が必要となります(別名:WebRPCパラメータ)。 これら2つの引数は LoadBalancingClient.OpWebRpc
メソッドに渡すことが可能です。
UriPath
はWebRPCの相対パスで、リモートプロシージャ名と合致する必要があります。
URL自体でパラメータを送信することも可能です。 この場合、クエリ文字列 はプロシージャ名に含め、相対パスに加える必要があります。
リクエストがPhoton Serverに受信されると、プロシージャ名はBaseURLに連結されて、同一のURLのWebサービスに送信される前にWebRPCのURLの絶対パスが生成されます。
使用されるHTPPリクエストメソッドがPOSTであるため、クライアントによって送信されるパラメータがある場合、PhotonはこれらのパラメータをデフォルトのプロパティとともにJSON POSTデータとして渡します:
AppVersion
: ゲームクライアントで設定される、アプリケーションのバージョン。UserId
: WebRPCを作成するアクターのID。
その他のプロパティは、クライアントから送信されるパラメータの一部です。
クライアントで使用されるWebRpcParameters
型がDictionary<string, object>
の場合、すべてのキー/値のセットはポストデータのルートオブジェクトに送信されます。
もし、その他のJSON有効型の場合には、その型は新たなプロパティRpcParams
の値として含まれます。
例 1
BaseURLはhttps://my.service.org
で、クライアントはWebRPC("method?id=1", parameters)
を呼びます。
パラメータは、{{"key1": 1}, {"key2": "yx"}, {"key3": true}}
をコンテンツとして持つDictionary<string, object>
です。
この場合、Photonはhttps://my.service.org/method?id=1
を呼び、さらにJSONをPOSTします:
例 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します:
例 3
BaseURLはhttps://my.service.org
で、クライアントはWebRPC("method?id=1", parameters)
を呼びます。
パラメータは初歩的で単純な型です。文字列は「test」としましょう。
この場合、Photonはhttps://my.service.org/method?id=1
を呼び、さらにJSONをPOSTします:
安全なデータを送信
WebRPCには利用可能な場合に、暗号化されたオブジェクトAuthCookieをWebサービスに安全に送信するオプションがあります。 これは、クライアントコードからWebRPCオペレーションメソッドを呼び出す際、適切なWebフラグ (SendAuthCookie = 0x02)を設定することで実行できます。
AuthCookie
は、カスタム認証プロバイダに対する認証が成功した後に取得できます。
詳細は、
カスタム認証のドキュメントページ
を参照してください。
レスポンス
WebRPCのためのWebサービスは、Photonがクライアントに結果を返送できるようにJSONオブジェクトでレスポンスする必要があります。
予期されるレスポンスにはResultCode
、Data
、または任意でMessage
.を含める必要があります。
ResultCode
はOKの場合は0、エラーの場合はその他のコードにしてください。 クライアントがエラーを処理できるよう、設定してください。
また、読み取り可能な文字列メッセージを追加することがベストプラクティスです。
Data
は空にすることが可能ですが、何かを送信する場合は有効なJSONオブジェクトでなければなりません。
例 1
例 2
例 3
WebRPCを選択する理由
HTTPリクエストの送信は、Photonなしでも実行できます。 HTTPクライアントは自分で記述することができ、またはSDKやライブラリから利用することも可能です。 ただし、Photon WebRPCの機能はそれだけにとどまりません。 以下が、Photon WebRPCを利用する利点です:
すべてのロジックを単独の接続されたクライアント内に保持して、単独の「ライフサイクル」と「ステートマシン」を処理することを推奨します。Photonクライアントならば、これらをすべて実現できます。
WebRPCオペレーションは、2つの方法でJSON直列化を考慮します。
AuthCookie
を使用してWebRPCに送信するか、またはさらに機密性の高いデータをサーバー間で送受信して、クライアントの正当性を確認できます。この機能の詳細についてはこちらを参照してください。
トラブルシューティング
以下に、WebRPCコールを作成した際に発生する可能性があるエラーコードと、その対処法を記載します。
OperationInvalid
(-2)
通常、このエラーはアプリケーションにサーバー側でWebRPCが設定されていないか、または有効化されていないことを示しています。
HttpLimitReached
(32745)
このエラーは、1秒間に作成するWebRPCリクエストが多すぎることを示しています。 エラーメッセージを確認し、上限数を確認してください。
ExternalHttpCallFailed
(32744)
このエラーは、設定された外部ウェブサービスと通信する際に問題が発生していることを示しています。 エラーメッセージで詳細を確認し、対処してください。