Service Extension アプリの作成

Last updated on July 14, 2026

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

Overview​

Extend Service Extension アプリは、gRPC サーバーと gRPC Gateway を含むスタックを使用して作成された RESTful ウェブサービスです。

一般的に、このスタックを使用してゼロから RESTful ウェブサービスを構築する手順は次のとおりです。

  1. protobuf (*.proto) ファイルを使用して gRPC サーバーを定義する。
  2. *.proto ファイルからスタブを生成し、gRPC サーバーを実装する。
  3. *.proto ファイルから gRPC Gateway コードを生成し、そのエントリーポイントを記述する。
  4. *.proto ファイルから OpenAPI 2.0 仕様を生成する。

ただし、Service Extension アプリテンプレートを使用すると、手順 1 と 2 のみを実行すればよくなります。残りの手順はビルド時に自動的に実行されるようパッケージ化されています。このアプリテンプレートには、認可が必要な RESTful エンドポイントを作成するのに役立つ gRPC サーバーインターセプターも含まれています。さらに、可観測性のための組み込みインスツルメンテーションも備えており、デプロイ時にメトリクスとログが利用可能になります。

この記事では、Extend Service Extension アプリテンプレートを変更し、要件に合わせた独自のアプリに変換する方法を説明します。

Prerequisites​

Extend Service Extension アプリテンプレートをクローンしていること。

git clone https://github.com/AccelByte/extend-service-extension-csharp

Project structure​

Extend Service Extension アプリのカスタマイズには、service.proto ファイルと MyService.cs ファイルの変更が含まれます。アプリは Program.cs の中で、gRPC サーバーなどの主要なコンポーネントを初期化します。RESTful エンドポイントへのリクエストが行われると、gRPC gateway がそれを処理し、対応する gRPC メソッドに転送します。myService.cs がリクエストに基づくカスタムロジックを実行する前に、authServerInterceptor.cs がリクエストに必要なアクセストークンと認可があることを最初に検証します。さらにカスタマイズが必要な場合を除き、他のファイルを変更する必要はありません。

.
├── src
│   ├── AccelByte.Extend.ServiceExtension.Server
│   │   ├── AccelByte.Extend.ServiceExtension.Server.csproj
│   │   ├── Classes
│   │   │   ├── AuthorizationInterceptor.cs   # gRPC server interceptor for access token authentication and authorization
│   │   │   └── ...
│   │   ├── Program.cs    # App starts here
│   │   ├── Protos
│   │   │   ├── service.proto   # gRPC server protobuf with additional options for exposing as RESTful web service
│   │   │   └── ...
│   │   ├── Services
│   │   │   └── MyService.cs    # gRPC server implementation containing the custom logic
│   └── extend-service-extension-server.sln
└── ...

Modify the protobuf​

アプリテンプレートでは、このファイルは src/AccelByte.Extend.ServiceExtension.Server/Protos/service.proto にあります。

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


service Service {

  rpc CreateOrUpdateGuildProgress (CreateOrUpdateGuildProgressRequest) returns (CreateOrUpdateGuildProgressResponse) {
    option (permission.action) = CREATE;
    option (permission.resource) = "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD";
    option (google.api.http) = {
      post: "/v1/admin/namespace/{namespace}/progress"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Update Guild progression"
      description: "Update Guild progression if not existed yet will create a new one"
      security: {
        security_requirement: {
          key: "Bearer"
          value: {}
        }
      }
    };
  }
  
  message CreateOrUpdateGuildProgressRequest {
    string namespace = 1;
    GuildProgress guild_progress = 2;
  }

  message CreateOrUpdateGuildProgressResponse {
    GuildProgress guild_progress = 1;
  }
  
}

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Service 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";
      }
    }
  };
};

Extend Service Extension の service.proto ファイルは、基本的に通常の gRPC サーバー定義に、以下の追加オプションを加えたものです。

  1. option (google.api.http)

    gRPC メソッドと RESTful エンドポイントの関係を記述します。詳細については、gRPC-Gateway のドキュメントを参照してください。

  2. option (permission.resource) および option (permission.action)

    各 RESTful エンドポイントを呼び出すために必要なパーミッションリソースとアクションを記述します。これにより、有効な AGS アクセストークンとパーミッションを必要とするエンドポイントを作成できます。

    パーミッションリソースとアクションの値は、同梱の gRPC サーバーインターセプターが認可を行う際に使用します。

    • option (permission.resource): AGS フォーマットを使用したパーミッションリソース文字列をここに指定できます。

    • option (permission.action): このオプションの有効な値は CREATE、READ、UPDATE、または DELETE です。詳細については、AGS パーミッションアクションを参照してください。

    備考

    AGS Public Cloud でカスタムパーミッションを作成するには、Public Cloud カスタムパーミッションを参照してください。その後、新しく作成したカスタムパーミッションを option (permission.resource) の値として使用できます。

  3. option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) および option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation)

    OpenAPI 2.0 仕様を生成するための情報を提供します。詳細については、gRPC-Gateway のドキュメントを参照してください。

Generate stubs from protobuf​

以下のコマンドを実行して、proto ファイルからスタブを生成します。

make proto    # Generate gateway code and swagger JSON
make build    # Some protobuf code is generated on-the-fly during build
important

service.proto ファイルを変更した後は、必ず上記のコマンドを実行してスタブを再生成してください。

Implement request handlers​

アプリプロジェクトでは、以下の内容が src/AccelByte.Extend.ServiceExtension.Server/Services/MyService.cs にあります。

サービスをセットアップするには、Service.ServiceBase から派生したクラスを作成します。このクラスがサービス実装として機能します。

using System;
using System.Threading.Tasks;

using Microsoft.Extensions.Logging;

using Grpc.Core;
using AccelByte.Sdk.Api;
using AccelByte.Extend.ServiceExtension.Server.Model;


namespace AccelByte.Extend.ServiceExtension.Server.Services
{
    public class MyService : Service.ServiceBase
    {
        public MyService()
        {
                                    
        }

        // Implement your service logic in here
    }
}

CreateOrUpdateGuildProgress 関数を実装するには、以下のようにメソッドをオーバーライドします。

public override Task<CreateOrUpdateGuildProgressResponse> CreateOrUpdateGuildProgress(CreateOrUpdateGuildProgressRequest request, ServerCallContext context)
{
    // Implementation goes here
}

GetGuildProgress 関数についても同様です。

public override Task<GetGuildProgressResponse> GetGuildProgress(GetGuildProgressRequest request, ServerCallContext context)
{
    // Implementation goes here
}
備考

gRPC のリクエスト処理の詳細については、リクエストの処理を参照してください。

Run the app locally​

リクエストハンドラーの実装が完了したら、アプリを実行して変更をローカルでテストします。

make run
に最終更新
On this page