Extend Event Handler アプリに REST API エンドポイントを追加する

Last updated on May 25, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要

Extend Event Handler アプリは、Kafka イベントの処理に加えて、REST API エンドポイントを公開できるようになりました。これは Extend Service Extension と同じ gRPC Gateway スタックを使用するため、単一の Extend アプリで AGS イベントへの反応とカスタム RESTful エンドポイントの提供の両方を行えます。

例えば、プレイヤーがログインしたときに報酬を付与する Event Handler アプリ (イベント駆動) を構築しながら、報酬履歴を照会する管理用 REST エンドポイント (リクエスト駆動) を公開することもできます。

備考

この機能は AGS 2026.2 リリース以降で利用できます。

仕組み

Event Handler アプリは、Kafka イベントを受信するためにすでに gRPC サーバーを実行しています。REST API サポートでは、gRPC Gateway がスタックに追加されます。

既存のイベントハンドラーサービス定義と並行して、google.api.http アノテーションを使用して protobuf ファイル内に REST エンドポイントのマッピングを定義します。
ビルド時に、protobuf から gRPC Gateway コードと OpenAPI 仕様が生成されます。
実行時には、gRPC Gateway が受信した HTTP リクエストを gRPC 呼び出しに変換し、gRPC サーバーのメソッドに転送します。

これは Extend Service Extension で使用されているアーキテクチャと同じです。詳細な図については、Extend Service Extension の概要を参照してください。

前提条件

Event Handler スタートガイドを完了し、Event Handler アプリテンプレートに慣れていること。
REST API 対応の Event Handler アプリテンプレートをクローンしていること。

注記

REST API 対応の Event Handler アプリテンプレートは現在開発中です。利用可能になり次第、テンプレートリポジトリへのリンクをここに追加します。

protobuf で REST API エンドポイントを定義する

protobuf ファイルには、イベントハンドラーサービス定義と REST エンドポイント定義の両方が含まれます。REST エンドポイントを追加するには、Extend Service Extension と同じように、gRPC メソッドに google.api.http、permission、および OpenAPI オプションのアノテーションを付けます。

次の例は、イベントハンドラーメソッドと REST エンドポイントの両方を定義する protobuf ファイルを示しています。

import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "permission.proto";

// Kafka イベントを処理するイベントハンドラーサービス
service EventHandlerService {
  // このメソッドは UserLoggedIn イベントが発生したときに Kafka Connect によって呼び出されます
  rpc OnUserLoggedIn (UserLoggedInEvent) returns (EventHandlerResponse);
}

// カスタムエンドポイント用の REST API サービス
service RewardService {

  rpc GetRewardHistory (GetRewardHistoryRequest) returns (GetRewardHistoryResponse) {
    option (permission.action) = READ;
    option (permission.resource) = "ADMIN:NAMESPACE:{namespace}:REWARD:HISTORY";
    option (google.api.http) = {
      get: "/v1/admin/namespace/{namespace}/rewards/history"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Get reward history"
      description: "Retrieve the history of rewards granted by the event handler"
      security: {
        security_requirement: {
          key: "Bearer"
          value: {}
        }
      }
    };
  }
}

message GetRewardHistoryRequest {
  string namespace = 1;
}

message GetRewardHistoryResponse {
  repeated RewardRecord records = 1;
}

message RewardRecord {
  string user_id = 1;
  string item_id = 2;
  string granted_at = 3;
}

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Event Handler with REST API";
    version: "1.0";
  };
  schemes: HTTP;
  schemes: HTTPS;
  base_path: "/service";

  security_definitions: {
    security: {
      key: "Bearer";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "Authorization";
      }
    }
  };
};

主要なアノテーションは以下のとおりです。

option (google.api.http) — gRPC メソッドを RESTful エンドポイントにマッピングします。詳細は gRPC-Gateway のドキュメントを参照してください。
option (permission.resource) および option (permission.action) — エンドポイントを呼び出すために必要な AGS 権限を定義します。gRPC サーバーインターセプターはこれらの値を使用して認可を行います。有効なアクションは CREATE、READ、UPDATE、DELETE です。詳細は AGS 権限アクションを参照してください。
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) および option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) — OpenAPI 2.0 仕様を生成するためのメタデータを提供します。詳細は gRPC-Gateway OpenAPI のドキュメントを参照してください。

スタブとゲートウェイコードを生成する

protobuf ファイルを変更した後は、スタブとゲートウェイコードを再生成します。

注記

以下のコマンドは、現在開発中の REST API 対応 Event Handler アプリテンプレートに基づいています。最終的なテンプレート構造によっては、正確なコマンドが異なる可能性があります。

C#
Go
Java
Python

make proto    # ゲートウェイコードと swagger JSON を生成
make build    # 一部の protobuf コードはビルド中にオンザフライで生成されます

make proto    # protobuf コード、ゲートウェイコード、swagger JSON を生成

make proto    # ゲートウェイコードと swagger JSON を生成
make build    # 一部の protobuf コードはビルド中にオンザフライで生成されます

make proto    # protobuf コード、ゲートウェイコード、swagger JSON を生成

重要

スタブを再生成するため、protobuf ファイルを変更したら必ず上記のコマンドを実行してください。

リクエストハンドラーを実装する

スタブを生成した後は、REST エンドポイントを支える gRPC サービスメソッドを実装します。実装パターンは Extend Service Extension と同じです。各言語の詳細な例については、独自の Extend Service Extension アプリを作成するを参照してください。

イベントハンドラーメソッドと REST エンドポイントメソッドは、同じアプリ内で共存できます。イベントハンドラーメソッドは Kafka Connect によって呼び出され、REST エンドポイントメソッドは gRPC Gateway を介して呼び出されます。

REST API エンドポイントをテストする

REST エンドポイントをローカルでテストするには、アプリを起動して gRPC Gateway ポートに HTTP リクエストを送信します。

# 例: 報酬履歴を照会
curl -X GET "http://localhost:8000/service/v1/admin/namespace/mygame/rewards/history" \
  -H "Authorization: Bearer <your-access-token>"

注記

PLUGIN_GRPC_SERVER_AUTH_ENABLED が true に設定されている場合、アプリは適切な権限を持つ有効な AGS アクセストークンを必要とします。ローカル開発中に認証をバイパスするには、false に設定してください。

Postman や任意の HTTP クライアントなどのツールも使用できます。自動生成された OpenAPI 仕様 (Swagger JSON) はアプリテンプレート内で利用でき、これらのツールにインポートすると便利です。

Event Handler の REST API と Service Extension のどちらを選ぶか

備考

アプリが (Kafka を介した AGS イベントへの反応を伴う) イベント駆動ロジックと、カスタム REST エンドポイントの両方を単一のデプロイメントで必要とする場合は、REST API を備えた Event Handler を使用してください。イベント処理なしでカスタム REST エンドポイントのみが必要な場合は、Extend Service Extension を使用してください。

概要​

仕組み​

前提条件​

protobuf で REST API エンドポイントを定義する​

スタブとゲートウェイコードを生成する​

リクエストハンドラーを実装する​

REST API エンドポイントをテストする​

Event Handler の REST API と Service Extension のどちらを選ぶか​

概要

仕組み