Service Extension アプリの作成

Last updated on February 4, 2026

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

概要​

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

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

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

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

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

前提条件​

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

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

プロジェクト構造​

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
└── ...

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 Private Cloudでは、カスタム権限リソースを作成できますが、AGS Shared Cloudでは、利用可能なものから選択することに制限されます。

  3. option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger)とoption (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation)

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

protobufからスタブを生成​

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

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

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

リクエストハンドラーの実装​

アプリプロジェクトでは、次のファイルが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)
{
    // 実装をここに記述
}

GetGuildProgress関数も同様です。

public override Task<GetGuildProgressResponse> GetGuildProgress(GetGuildProgressRequest request, ServerCallContext context)
{
    // 実装をここに記述
}
備考

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

に最終更新
On this page