OmniGRPC クイックスタート

このチュートリアルでは、ダウンロードしたサンプルサーバーへBlueprintからログイン情報を送ります。C++の作業は必要ありません。

このチュートリアルで使用する機能（.protoの取り込みとUnary RPC）は、Free Editionでも利用できます。Free Editionの対応プラットフォームはWindows（Win64）のみです。

ここで使うUnary（ユーナリー）とは、データを1回送り、結果を1回受け取るもっとも基本的な通信方法です。

Blueprintの構成

このチュートリアルでは、同じPCでサンプルサーバーとUnreal Editorを動かします。セットアップを済ませてから進めてください。

    flowchart TD
	  Begin[BeginPlay] --> Create[Create Channel → 変数へ保存]
	  Create --> Valid{Channelは有効か}
	  Valid -->|はい| Wait[Wait for gRPC Channel Connected]
	  Valid -->|いいえ| Config[接続設定を確認]
	  Wait --> Result{On Connected の Success}
	  Result -->|true| Request[Make LoginRequest]
	  Result -->|false| Retry[接続失敗を表示]
	  Request --> Call[Call gRPC: Login]
	  Call -->|On Success| Response[LoginResponseを確認]
	  Call -->|On Error| Error[StatusのCodeとMessageを確認]
	  End[EndPlay] --> Cancel[実行中のActionをCancel]
	  Cancel --> Close[Close Channel]

1. サンプルサーバーをダウンロードする

OmniGRPC サンプルサーバー ダウンロードページを開き、使用する開発PCのOSに合うパッケージをダウンロードして展開します。

パッケージにはGUIアプリ、user_service.proto、TUTORIAL.md、THIRD_PARTY_NOTICES.mdが含まれます。macOSではDMGを開き、アプリと同じ場所にあるuser_service.protoも作業用フォルダーへコピーしてください。

2. サンプルサーバーを起動する

Windows

ZIPを展開し、OmniGrpcTestServer.exeをダブルクリックします。

macOS

DMG内のOmniGrpcTestServer.appをApplicationsへコピーし、ダブルクリックします。Apple Siliconではarm64、Intel Macではamd64のパッケージを使用します。

Linux

ZIPを展開します。Terminalで展開先へ移動し、<version>をダウンロードしたファイルのバージョンに置き換えて実行してください。

chmod +x OmniGrpcTestServer_<version>_linux-amd64.AppImage
./OmniGrpcTestServer_<version>_linux-amd64.AppImage

マウントに失敗する環境では、起動コマンドの末尾に--appimage-extract-and-runを付けて実行します。

起動結果を確認する

アプリはチュートリアルが終わるまで起動したままにします。待ち受けアドレスは次回起動時にも引き継がれます。

サンプルサーバーの通信は暗号化されません。インターネットへ公開せず、ローカルPC上で使用してください。

3. .protoを取り込む

ダウンロードしたパッケージにあるuser_service.protoを、Unreal EditorのContent Browserへドラッグします。このファイルには、サンプルサーバーへ送るデータと受け取るデータの形が書かれています。内容は書き換えずに取り込んでください。

次のアセットが生成されていることを確認します。

• LoginRequest Struct
• LoginResponse Struct
• UserService Service Asset

生成結果の詳しい説明はセットアップを参照してください。

4. Channelを作成する

接続設定と保存先

Make Insecure Channel Configノードを追加し、Hostを127.0.0.1、Portを50051に設定します。この設定をCreate Channelノードへつなぎ、戻り値をOmniGrpcChannel型の変数に保存します。

Channelはサーバーとの接続を管理するオブジェクトです。同じサーバーと複数回通信する場合は、Channelを再利用します。このチュートリアルではLevel Blueprintの変数へ保存します。

接続完了を待つ

戻り値が有効か確認してから、Wait for gRPC Channel ConnectedへChannelを渡し、Timeout Secondsを5.0にします。On ConnectedのSuccessをBranchへつなぎ、trueの場合だけ次のLoginを実行してください。falseの場合は接続失敗を表示します。

On Connectedは接続失敗時にもfalseで呼ばれます。この例ではOn Connectedだけで成功・失敗を分岐し、On Timeoutには処理をつなぎません。両方に失敗処理をつなぐと、同じ処理を二重に実行してしまいます。

Insecureは「通信を暗号化しない」という意味です。この設定はサンプル専用です。公開するゲームやアプリではデータ型と運用設定のTLS設定を使用してください。

5. LoginRequestを作成する

生成されたMake LoginRequestノードを追加し、Usernameをalice、Passwordをtutorialに設定します。このStructがサーバーへ送るログイン情報です。

サンプルサーバーはパスワードを検証しません。この例は通信の確認用であり、本番用の認証処理ではありません。実際のパスワードを入力したり、ログや画面へ出したりしないでください。

6. Login RPCを実行する

1. Blueprintグラフを右クリックしてgRPCを検索し、Call gRPC Unaryノードを追加します。
2. ノードのServiceに生成済みのUserServiceを設定します。
3. ノードを選択し、DetailsパネルのgRPC → Method NameでLoginを選びます。

MethodはDetailsパネルで選択します。Method入力ピンはありません。候補には選択したServiceのUnaryメソッドだけが表示されます。

選択後はノード名がCall gRPC: Loginになり、Request／ResponseピンがLoginRequest／LoginResponseに切り替わります。接続待ちの成功側からこのノードを実行します。

Unaryノードには、開始直後に続くThen出力がありません。途中でCancelするためにActionを保存する場合は、接続待ちの成功側にSequenceを置き、Then 0でLoginを呼び、Then 1でLoginノードのAction出力を変数へ保存します。

7. 実行結果を処理する

EditorでPlayを実行します。通信に成功するとOn Successが呼ばれます。ResponseをBreak LoginResponseで分解し、次の値を確認してください。

実際のサービスで受け取ったトークンは変数へ保存し、次の通信の認証に利用できます。トークンはパスワードと同じように扱い、ログへ表示しないでください。

通信に失敗するとOn Errorが呼ばれます。StatusをBreakノードで分解し、CodeとMessageを確認してください。よく使うCodeと対応例は次のとおりです。

8. Channelとサンプルサーバーを終了する

Levelやゲームが終了するときは、保存したActionが有効ならCancelを呼び、その後にClose Channelを呼びます。Close Channelだけでは進行中のRPCは中止されません。閉じたChannelは再利用できないため、次回の通信時に新しいChannelを作成します。

サンプルサーバーは「停止」で待ち受けを止め、「終了」またはウィンドウを閉じる操作でアプリを終了します。

エラー処理も試す

これらはサンプルサーバー専用の入力値です。設定を変えたらPlayを再実行し、On Errorの処理を確認します。

トラブルシューティング

1. サーバーが127.0.0.1:50051で待ち受けているか。
2. ダウンロードパッケージに含まれるuser_service.protoをインポートしたか。
3. Call gRPC UnaryのServiceにUserService、DetailsのMethod NameにLoginを選んだか。
4. On ErrorのCodeとMessageに何が表示されているか。
5. Firewall、VPN、モバイル端末からの到達経路に問題がないか。

目的別の次の実装はユースケース別ガイドへ進んでください。