Blueprint APIリファレンス

このページでは、OmniGRPCのBlueprintノード、設定項目、イベントについて説明します。ノード名または項目名から、該当する説明を参照してください。

クラス名はUOmniGrpcLibraryの形式で表記します。Blueprintで使用する場合、C++による実装は不要です。各機能の見出しには、Blueprintに表示されるノード名を記載しています。

このドキュメントでは、Full Editionでだけ使用できる機能に、次のマークを付けています。Full Edition のみ マークがない機能は、Free Editionでも使用できます。

API全体の関係

    flowchart TD
	  Config[Channel Config] --> Channel[Channelを作成・保持]
	  Service[Service Asset + Method Name] --> Call[Call gRPCノード]
	  Channel --> Call
	  Request[Request Struct] --> Call
	  Call --> Action[Action出力を保存]
	  Call --> Event[結果イベントでResponse / Statusを処理]
	  Action --> Control[Send Message / Close Send / Cancel]

Send MessageとClose SendはClient／Bidi StreamingのActionで使用します。Unary／Server StreamingではRequestを開始ノードに渡します。

UOmniGrpcLibrary

Blueprintグラフを右クリックし、gRPCで検索すると表示される基本ノードです。

Create Channel

接続設定からChannelを作成します。Channelはサーバーとの接続を管理するオブジェクトです。作成したChannelは変数へ保存し、同じサーバーとの通信で再利用します。Hostが空など、作成に失敗した場合は戻り値が空になります。

有効なChannelが返っても、接続成功を意味するわけではありません。到達不能な接続先や証明書のエラーは、接続待ちやRPC実行時に確認してください。

Close Channel

Channelを閉じます。ゲーム終了時や、接続先を変更するときに呼びます。閉じたChannelでは新しい通信を開始できません。進行中のRPCは継続するため、中止する場合は各ActionのCancelを先に呼んでください。複数回呼び出しても安全です。

Make Insecure Channel Config

暗号化しない接続設定を作成します。ローカルPCでサンプルサーバーを実行する場合など、開発中の確認に使用します。本番環境では使用しないでください。

Make TLS Channel Config

通信を暗号化するTLS接続設定を作成します。一般に公開されているWebサービスと同じ種類の証明書を使用するサーバーへの接続に使用します。

Make TLS Custom Root Channel Config

独自の証明書を使用して通信を暗号化する接続設定を作成します。社内サーバーや自己署名証明書を使用する場合に、PEM形式のルート証明書を指定します。

Status to String

通信結果のCodeを文字列へ変換します。デバッグ表示に利用できます。ゲームの利用者にはCodeをそのまま見せず、「サーバーへ接続できませんでした」など分かりやすい文章へ置き換えることをおすすめします。

Load Service Descriptor Set

Service Assetの情報を事前に読み込みます。通常のCall gRPCノードでは自動的に読み込まれるため、ほとんどの場合は使用しません。特殊な初期化処理で先に読み込みたい場合に使用します。

Decode Response

受信したprotobufのバイトデータを、BlueprintのResponse Structへ変換します。通常のCall gRPCノードは変換済みのResponseを返すため、このノードは使用しません。バイトデータを直接扱う高度な処理向けです。

Call gRPCノード

共通の設定方法

Serviceピンに生成済みService Assetを設定し、ノードを選択してDetailsのgRPC → Method NameからMethodを選びます。候補にはノードの通信方法に合うMethodだけが表示されます。選択後はRequest／Responseの型とノード名が更新されます。

Method Nameはノードの設定項目であり、入力ピンではありません。実行中に文字列を差し替える用途ではなく、編集時に呼び出すMethodを確定するための設定です。

Call gRPC Unary

データを1回送り、結果を1回受け取る通信を開始します。ServiceとMethodを選ぶと、Request／Responseピンが対応するStructへ自動的に切り替わります。

Call gRPC Server Streaming

データを1回送信し、サーバーから結果を複数回受信する通信を開始します。進捗表示や一覧の連続受信に適しています。

Call gRPC Client Streaming

複数のデータを送り、最後にサーバーから結果を受け取る通信を開始します。開始ノードの戻り値を変数へ保存し、その変数からSend Messageを呼んでデータを送ります。

Call gRPC Bidi Streaming

送信と受信を同時に続ける通信を開始します。開始ノードの戻り値を変数へ保存し、Send Messageで送信します。サーバーから届いたデータはOn Message Receivedで受け取ります。

入出力と終了イベントの比較

4種類ともChannel、Service、Metadata、Timeout、Optionsを入力し、Actionを出力します。Client／Bidi StreamingではThenからActionを変数へ保存し、その後の送信処理へ進みます。開始ノードのThenは通信完了の通知ではありません。

UOmniGrpcChannel

Get Config

Channelを作ったときの接続設定を取得します。Host、Port、Securityなどを確認できます。アクセストークンや秘密鍵は画面やログへ表示しないでください。

Is Valid

Channelが正しく作られていればtrueになります。trueでも、サーバーへ接続できているとは限りません。現在の接続状態はGet Channel Stateで確認します。

Close

このChannelを閉じます。LibraryのClose Channelと同じ目的です。

Get Channel State

現在の接続状態を返します。Try to Connectをtrueにすると、まだ接続を始めていない場合も接続を試します。Readyなら通信可能です。作成前またはClose後はShutdownです。

UOmniGrpcServiceAsset

Find Method

Method名から、そのMethodの詳細情報を取得します。見つかった場合はtrueです。Methodの選択画面やデバッグ画面を実装する場合に使用します。

Get Method Names

Serviceに含まれるMethod名の一覧を返します。Methodを選ぶメニューなどに利用できます。

UOmniGrpcCallUnaryAction

On Success／On Error

Unary通信の結果を受け取るイベントです。成功時はOn Success、失敗時はOn Errorのどちらかが1回だけ呼ばれます。

Cancel

実行中の通信を中止します。中止されると通常はCancelledとしてOn Errorが呼ばれます。通信がすでに終わっていた場合はfalseを返します。

UOmniGrpcCallServerStreamingAction

On Message Received

サーバーからデータを受信するたびに呼ばれます。データが1件もないまま正常終了することもあります。

On Completed／On Error

通信が正常に終わるとOn Completed、エラーで終わるとOn Errorが呼ばれます。

Cancel

実行中の通信を中止します。画面を閉じて受信が不要になった場合などに呼びます。

UOmniGrpcCallClientStreamingAction

Send Message

サーバーへデータを1件送ります。開始したMethodのRequest Structを渡してください。通信中かつClose Send前なら繰り返し呼び出せます。trueは送信キューへの受付を意味し、サーバーの処理成功を保証するものではありません。falseの場合は通信状態やRequestの型を確認します。

Close Send

「こちらから送るデータはこれで最後です」とサーバーへ伝えます。Client Streamingで結果を受け取るために必ず呼んでください。

On Message Received

サーバーから結果が届いたときに呼ばれます。一般的なClient Streamingでは結果は1件です。

On Completed／On Error

通信が終わったときに呼ばれます。結果を受け取るイベントとは別に、画面表示の更新や変数の後片付けを行います。

Cancel

通信全体を途中で中止します。Close Sendは正常に送信を終える操作、Cancelは通信自体を中止する操作です。

UOmniGrpcCallBidiStreamingAction

Send Message

サーバーへデータを1件送ります。サーバーからの受信とは別のタイミングで何度でも呼べます。

Close Send

「こちらから送るデータはこれで最後です」とサーバーへ伝えます。そのあとも、サーバーから届く残りのデータは受信できます。

On Message Received／On Completed／On Error

データを受信するたびにOn Message Receivedが呼ばれます。通信の正常終了はOn Completed、エラー終了はOn Errorで受け取ります。送ったデータと届くデータの対応関係は、接続するサーバーの仕様を確認してください。

Cancel

双方向の通信を途中で中止します。

UOmniGrpcWaitForConnectedAction

Wait for gRPC Channel Connected

Channelが通信可能なReady状態になるまで待ちます。待っている間もゲームの処理は止まりません。Channelが空または無効な場合はActionを作成できないため、呼び出し前に有効性を確認してください。

通常はOn ConnectedのSuccessだけで成功・失敗を分岐します。両イベントへ同じ失敗処理を接続すると二重実行になります。接続待ちのTimeout Secondsには、5.0など正の値を指定してください。

UOmniGrpcHealthCheckAction

Check gRPC Health

サーバーが正常に動いているかを確認します。Service Nameを空にするとサーバー全体を確認し、Service名を入力するとそのServiceだけを確認します。この確認のために.protoを追加する必要はありません。

On ResultのStatusがOKであることを確認してから、Serving Statusを確認してください。Statusがエラーの場合は、サーバーの状態を取得できていません。

公開構造体

以下はBlueprintのMake／Breakノードで設定・確認できるStructです。必要な項目を設定し、使用しない項目は初期値のままとします。

FOmniGrpcChannelConfig

FOmniGrpcCallOptions

FOmniGrpcMetadataEntry

FOmniGrpcStatus

FOmniGrpcRetryPolicy

自動再試行の回数と間隔、再試行するエラーの種類を設定します。MaxAttempts = 1の場合は再試行しません。詳しくはデータ型と運用設定を参照してください。

FOmniGrpcMethodDescriptor

Method名、送受信するStruct、通信方法など、そのMethodを呼び出すための情報を保持します。通常はService AssetとMethodを選ぶと自動的に使用されます。

公開列挙型

EnumはBlueprintで選択肢として表示されます。主な内容は次のとおりです。EOmniGrpcServingStatusはHealth Check（Full Edition のみ）で使用します。