OmniGRPC ユースケース別ガイド

このページでは、認証、データの連続受信、ストリーミングなど、目的別の実装方法を説明します。各ピンの詳細はBlueprint APIリファレンスを参照してください。

gRPCには4種類の通信方法があります。目的に応じて、次の表から選択してください。Server Streaming、Client Streaming、Bidi Streamingの3種はFull Editionでだけ使用できます。

サンプルサーバーでは、次のMethodで各方式を試せます。CallノードのServiceにUserServiceを設定し、DetailsのMethod Nameで選択してください。

アクセストークンを使用して認証する

1. TLSを使ったChannelを作成します。
2. Call gRPC Unaryでログイン用Methodを呼び出します。
3. 受け取ったアクセストークンを変数へ保存します。
4. 以降の通信では、Call OptionsのAccess Tokenへ保存した値を設定します。
5. トークンの有効期限が切れたら、もう一度ログインします。

同じChannelのすべての通信で同じトークンを使う場合は、Channel ConfigのAccess Tokenへ設定することもできます。個別のCall Optionsに設定した値がある場合は、そちらが優先されます。

Unary RPCを実行する

ログイン、ユーザー情報の取得、設定の保存など、データを1回送って結果を1回受け取る処理ではUnaryを使います。

• 使用ノード: Call gRPC Unary
• 送るデータ: Request
• 成功時: On SuccessからResponseを受け取る
• 失敗時: On ErrorからStatusを受け取る
• 途中で止める: 戻り値のActionからCancelを呼ぶ

同じサーバーへ接続する場合はChannelを再利用します。画面を閉じて結果が不要になった場合や、別の条件で検索し直す場合は、古い通信をCancelしてから新しい通信を開始します。

Server Streamingでデータを連続受信する

ランキングの一覧、処理の進み具合、監視データ、AIが生成中の文章など、1回のRequestに対してサーバーからデータが何度も届く処理ではServer Streamingを使います。

1. Call gRPC Server StreamingでRequestを送ります。
2. On Message ReceivedのたびにUIやローカル状態を更新します。
3. On Completedで正常終了を確定します。
4. On Errorでエラーを処理します。
5. 画面を閉じる場合は、開始時に変数へ保存したActionからCancelを呼びます。

On Message Receivedの処理中もゲームは動いています。受信のたびに非常に重い処理を行うと画面が止まることがあるため、画像処理や大量の計算は小分けにしてください。

サンプルのWatchUsersでは、alice、bob、carolの3件を受信した後に正常終了します。

    sequenceDiagram
	  accTitle: Server Streamingの受信と終了
	  participant BP as Blueprint
	  participant Server as gRPCサーバー
	  BP->>Server: Requestを1回送信
	  loop データが届くたび
	    Server-->>BP: On Message Received
	  end
	  alt 正常終了
	    Server-->>BP: On Completed
	  else エラー終了
	    Server-->>BP: On Error
	  end

Client Streamingで複数のデータを送信する

複数のデータ登録、分割したファイルのアップロードなど、データを何度も送って最後に結果を1回受け取る処理ではClient Streamingを使います。

1. Call gRPC Client Streamingを開始し、ThenからAction出力を変数へ保存します。
2. データを送るたびにActionのSend Messageを呼びます。
3. すべて送信したら必ずClose Sendを呼びます。
4. On Message Receivedでサーバーから結果を受け取ります。
5. On CompletedまたはOn Errorで終了処理を行います。

Close Sendは、クライアント側の送信完了をサーバーへ通知するノードです。呼び出さない場合、サーバーが次のデータを待ち続け、結果を返せないことがあります。Close Sendの呼び出し後は、新しいデータを送信できません。

    sequenceDiagram
	  accTitle: Client Streamingの送信と終了
	  participant BP as Blueprint
	  participant Action as 保存したAction
	  participant Server as gRPCサーバー
	  BP->>Action: CallノードのThenで変数へ保存
	  loop データごと
	    BP->>Action: Send Message（LoginRequest）
	    Action->>Server: Request
	  end
	  BP->>Action: Close Send
	  Action->>Server: 送信完了を通知
	  Server-->>BP: On Message Received（UploadUsersResponse）
	  Server-->>BP: On Completed

図は正常終了の場合です。Send Messageがfalseなら送信を受け付けていません。エラーはOn Errorで処理し、画面を閉じるなど途中で不要になった場合はActionをCancelします。

サンプルのUploadUsersへaliceとbobを送ってからClose Sendすると、Accepted Count = 2、Summary = uploaded 2 users: alice,bobを受け取れます。

Bidi Streamingで双方向通信を行う

チャット、共同操作、遠隔制御など、こちらからの送信とサーバーからの受信を同時に続ける処理ではBidi Streamingを使います。

1. Call gRPC Bidi Streamingを開始し、ThenからAction出力を変数へ保存します。
2. 必要なタイミングでSend Messageします。
3. On Message Receivedは送信回数と独立して処理します。
4. こちらからの送信を終えるときはClose Sendします。
5. セッション自体を中止するときはCancelします。

送信と受信は別々のタイミングで行われます。「1件送ったら、必ずその結果が次に1件届く」とは限りません。どの送信に対する結果なのか区別する必要がある場合は、サーバー側の仕様にIDを含めてもらいます。

On Completedで正常終了、On Errorでエラー終了を処理します。Close Sendの後も受信は続くため、どちらかの終了イベントを受け取るまでActionを保持してください。

サンプルのUserLookupは、送ったUsernameごとにUserInfoを1件返します。aliceならUser Id = u-alice、Display Name = aliceです。

送信終了・通信中止・接続終了の違い

同じ接続先へ続けて通信する場合はChannelを残します。画面やゲームを終了する場合は、不要なActionをCancelしてからChannelを閉じてください。

サーバーの稼働状態を確認する

ロード画面での接続待ちや、オンライン状態の表示には、次の機能を組み合わせます。

• Get Channel State: 現在の接続状態をすぐに確認する
• Wait for gRPC Channel Connected: 接続できるまで指定時間だけ待つ
• Check gRPC Health:Full Edition のみ サーバーが実際に処理できる状態か確認する

Check gRPC HealthだけがFull Editionの機能です。Get Channel StateとWait for gRPC Channel Connectedは、Free Editionでも使用できます。

Channel StateがReadyでも、目的のServiceが停止している場合があります。確実に「オンライン」と表示したい場合は、Health Checkの成功まで確認します。

Wait for gRPC Channel ConnectedはOn ConnectedのSuccessで分岐してください。接続失敗時はOn Timeoutに加えてOn Connected(false)も呼ばれます。APIリファレンスにイベントの対応表があります。

通信を自動再試行する

一時的にサーバーへ接続できなかった場合に自動でやり直すには、Channel ConfigのRetry Policyを設定します。

• MaxAttempts: 最初の1回を含む最大試行回数
• InitialBackoff／MaxBackoff: 再試行まで待つ時間の最小値と最大値
• BackoffMultiplier: 失敗が続いたときに待ち時間を増やす倍率
• RetryableStatusCodes: 自動再試行するエラーの種類
• RetryPolicyServiceName: package名を含む正式なService名

決済、購入確定、アイテム付与など、重複実行が問題となる通信では、サーバー側の仕様を確認してから自動再試行を設定してください。

AI推論サービスへ接続する

• 画像を1枚送って結果を受け取る: Unary（Free／Full Edition）
• 生成中の文章を少しずつ受け取る: Server Streaming（Full Edition のみ）
• 音声を分割して送り、最後に全文を受け取る: Client Streaming（Full Edition のみ）
• 音声会話や対話セッション: Bidi Streaming（Full Edition のみ）

画像や音声などのデータが大きい場合は、MaxSendMessageBytes／MaxReceiveMessageBytesを確認し、必要なら圧縮を設定します。値はサーバー側の設定に合わせてください。

Android／iOS端末から接続する

AndroidとiOSへの対応は、Full Editionでだけ利用できます。Full Editionでは、PC向けと同じService AssetとBlueprintを利用できます。Android／iOSで追加確認が必要なのは、接続先、ネットワーク権限、証明書などの設定です。

端末の127.0.0.1は開発PCではなく端末自身です。LAN内の開発サーバーへ接続する場合は、端末から到達できるPCのIPまたはDNS名を使います。

公開するアプリではTLSを使用します。また、Wi-Fiとモバイル回線の切り替えや、アプリがバックグラウンドから戻ったときに接続が切れる場合があります。Channel Stateを確認し、必要に応じて再接続中の表示を出してください。