WebRPC

WebRPCを使用すれば、Photon Cloudに柔軟に外部サービスを統合することができます。 たとえば、WebRPCによってPhotonクライアントが外部Webサービスからデータをフェッチするようサーバーに要求することができます。 「メモリーデモ」では、プレイヤーのために保存されたゲームのリストを取得するためにGetGameList WebRPC が使用されます。 インベントリ、プロファイル、その他を簡単にフェッチすることが可能です。

目次

Webサービスの基礎

WebRPCアーキテクチャは単純です。

Photon Serverは、クライアントとWebサーバー間でプロキシまたはリレーの役割を果たします。

WebRPCはWebhookの拡張、またはクライアント主導のWebhookと考えることができます。

WebRPCを使用するには、HTTPベースのサービスを実装し、アプリケーションのWebhookセクション内でBaseURLを設定する必要があります。 Photon WebhookとWebRPCは、同一のBaseURLを共有しています。

開発の際には、以下のヒントを参照してください:

  • WebRPCにサービスを実装するには、あらゆる言語、フレームワーク、Webサーバーを使用することができます。
  • すべての場合において、送信するデータは最小化し、プレイヤーへの負荷を抑えてください。

リクエスト

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データとして渡します:

  • AppId: ゲームクライアントから設定されるAppID。アプリケーションのダッシュボードで参照してください。

  • AppVersion: アプリケーションのバージョンはゲームクライアントから設定されます。

  • Region: ゲームクライアントが接続するリージョン。

  • UserId: WebRPCを作成するアクターのID

その他のプロパティは、クライアントから送信されるパラメータの一部です。

クライアントで使用される WebRpcParameters型がDictionary<string, object>の場合、すべてのキー/値のセットはポストデータのルートオブジェクトに送信されます。 もし、その他のJSON有効型の場合には、その型は新たなプロパティRpcParamsの値として含まれます。

例 1

BaseURLはhttp://my.service.orgで、クライアントはWebRPC("method?id=1", parameters)を呼びます。 パラメータは、{{"key1": 1}, {"key2": "yx"}, {"key3": true}}をコンテンツとして持つDictionary<string, object>です。 この場合、Photonはhttp://my.service.org/method?id=1を呼び、さらにJSONをPOSTします:

例 2

BaseURLはhttp://my.service.orgで、クライアントはWebRPC("method?id=1", parameters)を呼びます。 パラメータはオブジェクトの配列です: object[] { 0, "xy", false } この場合、Photonはhttp://my.service.org/method?id=1を呼び、さらにJSONをPOSTします:

例 3

BaseURLはhttp://my.service.orgで、クライアントはWebRPC("method?id=1", parameters)を呼びます。 パラメータは初歩的で単純な型です。文字列は「test」としましょう。 この場合、Photonはhttp://my.service.org/method?id=1を呼び、さらにJSONをPOSTします:

安全なデータを送信

WebRPCには利用可能な場合に、暗号化されたオブジェクトAuthCookieをWebサービスに安全に送信するオプションがあります。

これは、クライアントコードからWebRPCオペレーションメソッドを呼び出す際、適切なWebフラグ (SendAuthCookie = 0x02)を設定することで実行できます。

AuthCookieは、カスタム認証プロバイダに対する認証が成功した後に取得できます。 詳細情報はカスタム認証ドキュメントページを参照してください。

レスポンス

WebRPCのためのWebサービスは、Photonがクライアントに結果を返送できるようにJSONオブジェクトで応答する必要があります。 予期されるレスポンスにはResultCodeData、また任意でMessageを含める必要があります。

ResultCodeはO​​Kの場合は0、エラーの場合はその他のコードにしてください。 クライアントがエラーを処理できるよう、設定してください。また、読み取り可能な文字列メッセージを追加することがベストプラクティスです。

Dataは空にすることが可能ですが、何かを送信する場合は有効なJSONオブジェクトでなければなりません。

Example 1

Example 2

Example 3

URLタグ

ダッシュボードからwebhookまたはWebRpcのベースURLを設定する場合、必要に応じて、クエリ文字列の一部として1つ以上の動的変数 を設定することができます。 これらの変数は、要求を送信する前に、バックエンドでそれぞれの値に置き換えられます。

それぞれのアプリケーションのユーザー・セグメントを個別に処理したい場合は、URLのタグを使用します。 Photonは、次のURLのタグに対応しています:

  • {AppVersion} クライアントによって設定されたアプリケーションのバージョンを渡します。
  • {AppId} アプリケーションのIDを渡します。
  • {Region} トリガークライアントが接続されているクラウドリージョンのトークンを渡します。例:"eu"
  • {Cloud} は、トリガークライアントが接続されているクラウドの名前を渡します。例:「public」または「enigmaticenterprise」

URLタグの例

  1. https://{Region}.mydomain.com/{AppId}?version={AppVersion}&cloud={Cloud} 例:パラメータとして渡される異なるホスト、バージョン、およびクラウドに各リージョンをルート。
  2. https://mydomain.com/{Cloud}/{Region}/{AppId}/{AppVersion} 構造化されたURIとしてすべてのタグを渡します。

WebRPCを選択する理由

HTTPリクエストの送信は、Photonなしでも実行できます。

HTTPクライアントは自分で記述することができ、またはSDKやライブラリから利用することも可能です。 ただし、Photon WebRPCの機能はそれだけにとどまりません。 以下が、Photon WebRPCを利用する利点です:

  • すべてのロジックを単独の接続されたクライアント内に保持して、単独の「ライフサイクル」と「ステートマシン」を処理することを推奨します。Photonクライアントならば、これらをすべて実現できます。

  • WebRPCオペレーションは、2つの方法でJSONシリアル化を考慮します。

  • 「BaseURL」とメソッド名はURLタグ機能をサポートします。
  • AuthCookieを使用してWebRPCに送信するか、またはさらに機密性の高いデータをサーバー間で送受信して、クライアントの正当性を確認できます。この機能の詳細についてはこちらを参照してください。

トラブルシューティング

以下に、WebRPCコールを作成した際に発生する可能性があるエラーコードと、その対処法を記載します。

  • OperationInvalid (-2)

通常、このエラーはアプリケーションにサーバー側でWebRPCが設定されていないか、または有効化されていないことを示しています。

  • HttpLimitReached (32745)

このエラーは、1秒間に作成するWebRPCリクエストが多すぎることを示しています。 エラーメッセージを確認し、上限数を確認してください。

  • ExternalHttpCallFailed (32744)

このエラーは、設定された外部ウェブサービスと通信する際に問題が発生していることを示しています。 エラーメッセージで詳細を確認し、対処してください。

GetGameList

この部分は、Photon製品には組み込まれていない特定な機能の例、GetGameListについて説明します。
私達のGitHubページで提供されているサンプルの1つを使用する場合は、リモート・プロシージャ名のスペルに注意してください。GetGamesListに「s」は含まれません。
または、任意の名前、あるいは任意のWebRPC実装を自由に選択できます。

GetGameListは、PhotonのWebRPC機能を実証するための「メモリデモ」で紹介した通り、特殊なWebRPCです。 ほとんどすべてのゲームは、以前に保存したゲームの一覧を取得する必要があるため、とても重要です。

その基本的な方法は、ウェブサービスにリクエストを送信し、発信ユーザが再参加し、プレイを継続するためのゲームリストを取得することです。 これは、アプリケーションが適切にダッシュボードから構成されることを前提としています。 BaseUrlはWebサービスを指し、ゲームデータを維持するためにはisPersistenttrueに設定し、GameClose のwebhookは有効にするべきです。ウェブサービスに返されるべきゲームデータはPhotonのシリアル化されたルーム状態に依存しているので、後者は重要です。

一方、ウェブサービスは保存されたゲームデータへのアクセス権を持つべきであり、WebRPCのパスに送信されたプロセスHTTP POSTリクエストを受信および処理する準備ができている必要があります (ここではGetGameList)。

PhotonはすべてのWebRPCリクエストデータにUserIDを送信しているので、カスタムパラメータを追加する必要はありません。リクエストは、追加の引数なしで送信されます。

ウェブサービスは、JSONオブジェクトとしてDataに保存されたゲームのリストを返すべきです。保存された各ゲームのGameIdはキーを持ちます。それぞれの値は、2つのプロパティで構成されるJSONオブジェクトです。

  • ActorNr:WebRPCを呼び出すアクターが最初にそのルームに参加したときに割り当てられものと全く同じActorNr。これは、以前、意図的に個別で保存された場合、簡単に読み込むことができます。また、ActorListにループしてUserIdを比較することにより、それぞれのルームの保存されたStateオブジェクトから取得できます。

  • Properties:それぞれのルームの保存されたStateに含まれるCustomPropertiesプロパティから取得可能なロビーに表示されるCustomRoomPropertiesのキー:値ペア。

{
   "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を呼び出す方がより理にかなっています。例:Masterサーバから。

ウェブサービスへのデータの受け渡し

WebRPCは、クライアントからウェブサービスににデータを渡す3つの異なる方法を提供します。3つの異なるタイプを別々に使用するか、組み合わせることができます。 例えば、GetGameListを拡張し、特定の相手に基づいて保存したゲームのフィルタリングされたリストを取得する場合、3つの異なる方法で行うことができます:

  1. RESTfulの方法:

    相対 URI: /GetGameList/{opponentId}

  2. POSTデータ:

    相対 URI: /GetGameList

    Request data:

  3. Query string (a.k.a. GET parameters):

    相対 URI: /GetGameList?opponentId={opponentId}

    もちろん、ウェブサービスは、選択された方法に従って更新する必要があります。

データ型の変換

このセクションでは、Photonクラウドとウェブサービスの間で交換されるデータ型のみが説明されています。クライアントとPhotonサーバ間のデータ型の詳細はPhotonページのシリアル化を参照してください。

Photon Cloud -> ウェブサービス

C# / .Net (Photonが対応するタイプ) JavaScript / JSON
byte number
short
int
long
double
bool bool
string string
byte array string (Base64 encoded)
array (対応されているタイプの[], 長さ < short.MaxValue) array
Hashtable (対応されているタイプの, カウント < short.MaxValue, Photon実装が望ましい) object
Dictionary (対応されているタイプのキーや値, カウント < short.MaxValue) object
null null

サンプルリクエストデータ(タイプは連結されます)

Photonクラウドから送信:

ウェブサーバによって読み込み:

ウェブサービス - >Photon Cloud

各JavaScript/JSONタイプをC#/.Netの同等のものに照らし合わせる表:

JavaScript / JSON C# / .Net
object Dictionary<string, object>
array object[]
number double
string string
boolean bool
null (タイプではない) null
未定義(送信時) null

サンプルのレスポンスデータ(タイプは連結されています)

ウェブサーバーから送信:

Photon Cloudから読み込み:

 ドキュメントのトップへ戻る