モジュール構造

Understand the structure of a Cloud Code module project and how it exposes endpoints.

読み終わるまでの所要時間 6 分

最終更新 1日前

Cloud Code モジュールは、ゲームクライアントが呼び出すことのできるエンドポイントを公開する単純な .NET プロジェクトです。モジュールは、同様のパラダイムを .NET クラスライブラリとして採用します。例えば、標準の C# クラスは以下のようになる場合があります。


namespace ModulesExample;public class Example{    private static string[] GetCheatCodes()    {        return new string[]        {            "LEAVEMEALONE",            "ASPIRINE",            "BIGBANG"        };    }    public void ChangeHaircut(string haircutName)    {    }}

コンパイルされると、クラス

Example

への参照は

ChangeHaircut()

メソッドのみを使用できます。


using ModulesExample;class UsageExample{    public void GameLoop()    {        Example.ChangeHaircut("buzzcut");        // Compile error "Cannot access private method 'GetCheatCodes()' here"        var cheatCodes = Example.GetCheatCodes();    }}

これにより、開発者はアクセスモディファイアを通じてライブラリのインターフェースを選択できます。Cloud Code モジュールは同じ方法で動作しますが、代わりに

[CloudCodeFunction("ChangeHaircut")]

属性を使用します。 Cloud Code モジュールでは、自己包含サーバー主導型ライブラリを作成できます。これにより、サーバーでゲームロジックを実行し、それをクライアントから呼び出すことができるため、ゲームロジックがクライアントからデタッチされ、セキュリティが向上します。モジュールは、コードの再利用を提供し、ゲームロジックの管理に使用できるインターフェースを提供します。

C# プロジェクト

Cloud Code モジュールプロジェクトは、クラスライブラリ C# プロジェクトです。プロジェクトは、ソリューションの一部にすることもできます。最も単純なプロジェクト構造は以下のようになります。


├─ Main.csproj└─ Dependencies└─ HelloWorld.cs

または、ソリューション内の場合は、以下のようになります。


Sample.sln├─ Main.csproj    └─ Dependencies    └─ HelloWorld.cs

ソリューションには、相互に参照する複数のプロジェクトを入れることもできます。これにより、テストプロジェクトを簡単に追加でき、コードの再利用が可能になります。以下の例は、有効なプロジェクト構造を示します。


Sample.sln├─ Main.csproj    └─ Dependencies    └─ HelloWorld.cs├─ Tests.csproj    └─ Dependencies    └─ Tests.cs├─ Other.csproj    └─ Dependencies    └─ Class1.cs

ただし、Cloud Code 関数を入れることができるのはメインプロジェクトだけです。 Cloud Code モジュールの単体テストの記述方法については、単体テストの作成を参照してください。適用されるストレージ制限を確認するには、Cloud Code 制限を参照してください。

メインプロジェクト

ソリューションには複数の C# プロジェクトを追加できますが、メインプロジェクトはモジュールごとに 1 つだけです。メインプロジェクトには、すべてのモジュールエントリーポイント (

CloudCodeFunction

属性がある関数) が含まれます。

注意

重要: メインプロジェクトの外部で任意の関数に

CloudCodeFunction

属性を設定した場合、Cloud Code サービスはそれらをエントリーポイントとして認識できません。

メインプロジェクトは、Cloud Code サービスにデプロイするプロジェクトでもあります。メインプロジェクトで参照されていないプロジェクトと依存関係は Cloud Code サービスにデプロイしません。メインプロジェクトの名前は、Cloud Code サービスにデプロイするアーカイブの名前と一致する必要があります。

注

ノート: 複数のメイン Cloud Code モジュールプロジェクトを含むソリューションを作成できます。この場合、各メインプロジェクトは異なるモジュールに対応します。

サンプルプロジェクト

最も単純なモジュールプロジェクトは、以下の構造を持ちます。


Sample.sln├─ Main.csproj    └─ Dependencies    └─ HelloWorld.cs

以下のサンプルは、文字列

Hello World!

を返す単一の関数

Hello

で Cloud Code モジュールを定義します。


using Unity.Services.CloudCode.Core;namespace Sample;public class HelloWorld{    [CloudCodeFunction("Hello")]    public string PrintHello()    {        return "Hello World!";    }}

Cloud Code NuGet パッケージ

.NET プロジェクトとして、Cloud Code モジュールプロジェクトはパッケージ化されたコードを共有するために NuGet も使用します。 NuGet の詳細については、Microsoft のドキュメントを参照してください。 Cloud Code は、モジュールに追加できる 2 つのパッケージを提供します。

```
com.Unity.Services.CloudCode.Core
```
: このパッケージには、
```
CloudCodeFunction
```
属性など、Cloud Code のコア機能が含まれています。すべての Cloud Code モジュールに、このパッケージが必要です。
```
com.Unity.Services.CloudCode.Apis
```
: これは、Cloud Code サービスを操作するために使用できる Unity Gaming Services API を含む任意のパッケージです。このパッケージを使用して、Cloud Save などの他の Cloud Code SDK を呼び出すことができます。

詳細については、Jetbrains Rider または Visual Studio でプロジェクト内の NuGet パッケージをインストールして使用する方法に関するドキュメントを参照してください。

注

ノート: モジュールプロジェクトで使用する外部 NuGet パッケージをインストールすることもできます。詳細については、外部サービスとのインテグレーションを参照してください。

コード構造

コード構造の問題を回避するには、以下のガイドラインに従います。

CloudCodeFunction 属性

メソッドを Cloud Code 関数としてマークし、実行可能な Cloud Code モジュールエンドポイントにするには、

CloudCodeFunction

属性を使用します。Cloud Code 関数属性は、モジュールのメインクラスでのみ使用できます。関数を呼び出すには、属性の名前を呼び出す必要があります。

メソッドシグネチャ

モジュール関数のメソッドシグネチャには以下の構造体を使用します。


[CloudCodeFunction("FunctionName")]public async Task<ReturnType> FunctionName(IGameApiClient gameApiClient, IExecutionContext ctx, string parameter1, string parameter2){    ...}

注意

重要:

async void

パターンはエラーの原因になります。常に

Task

または

Task<T>

を返します。非同期プログラミングのベストプラクティスについては、Microsoft の公式ドキュメントを参照してください。

注意

重要: Cloud Code は、Cloud Code 関数の静的メソッドをサポートしていません。

モジュールでのシングルトンパターンの使用

シングルトンパターンを使用して、Cloud Code C# パッケージと外部サービス呼び出しを統合できます。シングルトンパターンは、Cloud Code のパフォーマンスとスケーラビリティを改善し、同じオブジェクトの複数のインスタンスを作成しないようにします。依存性注入を使用して、モジュールに

IGameApiClient

および

IPushClient

インターフェースを挿入します。

注意

重要: 複数のワーカーが存在する場合、API 呼び出しが同じワーカー対象にする保証はないため、モジュール関数呼び出し間の共有状態に依存しないでください。

注意

重要: Cloud Code ワーカーには 256 MB のメモリ制限があります。この制限を超えたワーカーは、最終的にクラッシュします。

パラメーターを渡す

モジュール関数にパラメーターを渡すことができます。

プリミティブな型と複雑な型

これには、すべてのプリミティブな型 (

int

、

string

、

bool

、

float

など) と複雑な型 (

List<T>

、

Dictionary<T>

、

Dictionary<string, T>

など) が含まれます。例えば、モジュール関数に

string

と

List<string>

を渡すことができます。


{  "params": {    "parameter1": "a",    "parameter2": ["b", "c"]  }}

同じパラメーターを使用してモジュール関数を定義します。


[CloudCodeFunction("SimpleParams")]public async Task SimpleParams(IExecutionContext ctx, string parameter1, List<string> parameter2){  return parameter1 + parameter2[0] + parameter2[1];}

カスタム型

モジュールプロジェクトで定義したカスタム型を渡すこともできます。例えば、JSON オブジェクトをモジュールオブジェクトに渡すことができます。


{  "params": {    "player": {      "name": "player",      "health": 50,      "stamina": 20,      "inventory": {        "count": 5,        "weight": 20      }    }  }}

モジュールプロジェクトに

Player

クラスと

Inventory

クラスおよび関数を定義します。


public class Player{    public string Name { get; set; }    public int Health { get; set; }    public int Stamina { get; set; }    public Inventory Inventory { get; set; }}public class Inventory{    public int Count { get; set; }    public int Weight { get; set; }}[CloudCodeFunction("CustomParams")]public async Task<string> CustomParams(IExecutionContext ctx, Player player){    return $"{player.Name} has {player.Health} health and {player.Stamina} stamina and {player.Inventory.Count} items in their inventory with a total weight of {player.Inventory.Weight}";}

使用可能なインターフェース

Cloud Code モジュールは、

IGameApiClient

、

IAdminApiClient

、

IPushClient

および

IExecutionContext

インターフェースを使用して、モジュールの機能を拡張できます。

ICloudCodeSetup

インターフェースを使用して、モジュールの依存関係を管理できます。これについては、依存性注入のドキュメントを参照してください。

IGameApiClient インターフェース

IGameApiClient

インターフェースは、Cloud Code C# Client SDK にアクセスする方法を提供します。依存性注入を使用して、モジュールに

IGameApiClient

を挿入します。

ICloudCodeSetup

インターフェースを実装するクラスを定義し、

GameApiClient

をシングルトンとして追加します。


 public class ModuleConfig : ICloudCodeSetup{    public void Setup(ICloudCodeConfig config)    {        config.Dependencies.AddSingleton(GameApiClient.Create());    }}

```
IGameApiClient
```
インターフェースを関数パラメーターとしてモジュール関数に渡します。

IAdminApiClient インターフェース

IAdminApiClient

インターフェースは、Cloud Code C# Admin SDK にアクセスする方法を提供します。依存性注入を使用して、モジュールに

IAdminApiClient

を挿入します。

ICloudCodeSetup

インターフェースを実装するクラスを定義し、

AdminApiClient

をシングルトンとして追加します。


 public class ModuleConfig : ICloudCodeSetup{    public void Setup(ICloudCodeConfig config)    {        config.Dependencies.AddSingleton(AdminApiClient.Create());    }}

```
IAdminApiClient
```
インターフェースを関数パラメーターとしてモジュール関数に渡します。

IPushClient インターフェース

IPushClient

インターフェースは、プレイヤーにプッシュ通知を送信する方法を提供します。依存性注入を使用して、モジュールに

IPushClient

を挿入します。

ICloudCodeSetup

インターフェースを実装するクラスを定義し、

PushClient

をシングルトンとして追加します。


 public class ModuleConfig : ICloudCodeSetup{    public void Setup(ICloudCodeConfig config)    {        config.Dependencies.AddSingleton(PushClient.Create());    }}

```
PushClient
```
オブジェクトを関数パラメーターとしてモジュール関数に渡します。

Cloud Code からプッシュメッセージを送信する方法の詳細については、プッシュメッセージを参照してください。

IExecution コンテキスト

モジュール内の他の UGS サービスを呼び出すには、

IExecutionContext

インターフェースを使用して、現在の呼び出しに関する追加の情報を取得できます。以下の値を使用して、サービス SDK にアクセスし、どのプレイヤーがリクエストを行うかを確認できます。

```
ProjectId
```
: 呼び出し元が認証されたプロジェクト ID。
```
PlayerId
```
: スクリプトを実行したプレイヤー ID。ノート: サービスがスクリプトを呼び出す場合、プレイヤー ID は使用できません。
```
EnvironmentId
```
: モジュールの環境 ID。
```
EnvironmentName
```
: モジュールの環境名。
```
AccessToken
```
: プレイヤーが Cloud Code を認証するために使用した JSON Web Token (JWT) 認証情報。
```
UserId
```
: サービスアカウントのユーザー ID。(ノート: サービスがスクリプトを呼び出す場合、ユーザー ID は使用できません。)
```
Issuer
```
: 発行者またはサービスアカウントトークン。(ノート: プレイヤーがスクリプトを呼び出す場合、発行者は使用できません。) 例えば、Multiplay が呼び出す場合、発行者は
```
multiplay
```
です。
```
ServiceToken
```
: Cloud Code サービスアカウント JWT 認証情報。
```
AnalyticsUserId
```
: プレイヤーの Analytics ユーザー ID。(ノート: サービスがスクリプトを呼び出す場合、分析ユーザー ID は使用できません。)
```
UnityInstallationId
```
: プレイヤーの Unity デバイスインストール ID。(ノート: サービスがスクリプトを呼び出す場合、Unity インストール ID は使用できません。)

実行コンテキストを使用してプレイヤー ID を取得し、異なる Unity Gaming Services を認証できます。クラスのコンストラクタと、

CloudCodeFunction

属性を指定したメソッドの両方を通じて、実行コンテキストを取得できます。例えば、実行コンテキストを使用して Cloud Save を呼び出し、プレイヤーキーを取得できます。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;namespace Sample;public class HelloWorld{    private static ILogger<HelloWorld> _logger;    public CloudSaveSdkSample(ILogger<HelloWorld> logger)    {        _logger = logger;    }    [CloudCodeFunction("GetData")]    public async Task<object> GetData(IExecutionContext context, IGameApiClient gameApiClient, string key)    {        try        {            var result = await gameApiClient.CloudSaveData.GetItemsAsync(context, context.AccessToken,                context.ProjectId, context.PlayerId, new List<string> { key });            return result.Data.Results.First().Value;        }        catch (ApiException ex)        {            _logger.LogError("Failed to get data from Cloud Save. Error: {Error}", ex.Message);            throw new Exception($"Failed to get data for playerId {ctx.PlayerId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

トークン認証

AccessToken

と

ServiceToken

は

IExecutionContext

インターフェースの JWT とプロパティです。これらのトークンを使用して、Cloud Code から他の Unity Gaming Services の呼び出しを認証できます。

トークンタイプ	発生元	データアクセス	使用方法
`accessToken`	Authentication サービスによって生成されます。	認証されたプレイヤーのみ。	`AccessToken` は、Cloud Code 呼び出しを認証するために使用する JWT です。他の UGS サービスにトークンを渡して、認証されたプレイヤーのデータにアクセスできます。
`serviceToken`	Cloud Code によって生成されます。	クロスプレイヤーデータアクセス。	`ServiceToken` は、他の UGS サービスを呼び出し、クロスプレイヤーデータを操作するために使用するトークンです。

設定するアクセス制御ルールは

AccessToken

に影響します。以下のサンプルは、

AccessToken

を使用して、Cloud Save で認証されたプレイヤーのデータにアクセスする方法を示します。


using Microsoft.Extensions.DependencyInjection;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.CloudSave.Model;namespace TokenSample;public class TokenSample{    [CloudCodeFunction("GetKeysForAuthenticatedPlayer")]    public  Task<ApiResponse<GetKeysResponse>> GetPlayerKeys(IExecutionContext ctx, IGameApiClient gameApiClient)    {        try        {            // Using ctx.AccessToken to access the data for the player calling the function            return gameApiClient.CloudSaveData.GetKeysAsync(ctx, ctx.AccessToken, ctx.ProjectId, ctx.PlayerId);        }        catch (ApiException e)        {            throw new Exception($"Failed to get keys for playerId {ctx.PlayerId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

すべてのプレイヤーのデータにアクセスするには、

ServiceToken

を使用し、

playerId

のパラメーターを渡すことができます。


using Microsoft.Extensions.DependencyInjection;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.CloudSave.Model;namespace TokenSample;public class TokenSample{    [CloudCodeFunction("GetKeysForAnyPlayer")]    public  Task<ApiResponse<GetKeysResponse>> GetPlayerKeys(IExecutionContext ctx, IGameApiClient gameApiClient, string playerId)    {        try        {            // Using ctx.ServiceToken to access the data for any player            return gameApiClient.CloudSaveData.GetKeysAsync(ctx, ctx.ServiceToken, ctx.ProjectId, playerId);        } catch (ApiException e)        {            throw new Exception($"Failed to get keys for playerId {ctx.PlayerId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

2 つのトークンの違いの詳細な説明は、サービスとアクセストークンのドキュメントを参照してください。

Cloud Code モジュールメタデータ

Cloud Code モジュールとそのメタデータを取得するには、Cloud Code サービスに

GET

リクエストを送信します。レスポンスは、以下の構造を持つ JSON オブジェクトです。


{  "name": "string",  "language": "CS",  "tags": {    "property1": "string",    "property2": "string"  },  "signedDownloadURL": "string",  "dateCreated": "2022-04-05T09:12:13Z",  "dateModified": "2022-04-05T09:12:13Z"}

タグは、Cloud Code モジュールにアタッチできるキーと値のペアです。モジュールのバージョン、作成者、バージョン管理を使用する場合のコミットハッシュなど、必要な任意の情報をタグに記録できます。モジュールでは最大 10 個のタグを格納でき、タグキーとタグ値ごとに使用できる最大文字数は 128 です。

注

ノート: カスタムタグは、オーサリングに Cloud Code API を使用する場合のみサポートされます。オーサリングに Unity Gaming Services CLI や Unity エディターを使用する場合、タグは Cloud Code で無視されます。

署名付きダウンロード URL

署名付きダウンロード URL は、モジュールアーカイブをダウンロードするために使用できる一時的な URL です。

ドキュメント

Development

User Acquisition

Monetization

産業

ドキュメント

Development

User Acquisition

Monetization

産業

Cloud Code

Cloud Code

モジュール構造

C# プロジェクト

メインプロジェクト

サンプルプロジェクト

Cloud Code NuGet パッケージ

コード構造

CloudCodeFunction 属性

メソッドシグネチャ

モジュールでのシングルトンパターンの使用

パラメーターを渡す

プリミティブな型と複雑な型

カスタム型

使用可能なインターフェース

IGameApiClient インターフェース

IAdminApiClient インターフェース

IPushClient インターフェース

IExecution コンテキスト

トークン認証

トークンタイプ

発生元

データアクセス

使用方法

Cloud Code モジュールメタデータ

タグ

署名付きダウンロード URL