クロスプレイヤーデータの操作

Access and modify data for multiple players at once with Cloud Code modules.

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

最終更新 23日前

Cloud Code モジュールを使用して、一度に複数のプレイヤーのデータにアクセスして変更できます。これにより、以下のようなさまざまなユースケースが解放されます。

Cloud Save で一度に複数のプレイヤーのプレイヤーデータを更新します。
一度に複数のプレイヤーにプッシュ通知を送信します。
一度に複数のプレイヤーの Economy 残高を更新します。

注

ノート: 乱用のリスクを軽減するために、すべてのプレイヤーではなく特定のユーザーだけが、クロスプレイヤーデータを操作するモジュールを呼び出せることを確認します。特定のモジュールまたはそのエンドポイントへのアクセスを制限するには、アクセス制御を使用できます。

プレイヤー ID の取得

複数のプレイヤーを操作するには、最初に UGS サービスを呼び出してプレイヤー ID を取得する必要があります。プレイヤー ID を取得するには、

Com.Unity.Services.CloudCode.Apis

NuGet パッケージ内の Cloud Code C# SDK を使用できます。サービスの REST API ディレクトリを使用することもできます。プレイヤー ID を取得するために使用できるサービスには、Leaderboards、Lobby、Friends が含まれます。

Leaderboards の使用

最初に、リーダーボードを作成する必要があります。例えば、リーダーボードから上位 5 人のプレイヤーを取得し、その ID を保存できます。以下のモジュールは、リーダーボード ID を取り込み、上位 5 人のプレイヤーのスコアのリストを返します。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.Leaderboards.Model;namespace CrossPlayerData;public class CrossPlayerData{    private readonly ILogger<CrossPlayerData> _logger;    public CrossPlayerData(ILogger<CrossPlayerData> logger)    {        _logger = logger;    }    [CloudCodeFunction("GetTopPlayers")]    public async Task<List<LeaderboardEntry>> GetTopPlayers(IExecutionContext ctx, IGameApiClient gameApiClient, string leaderboardId)    {        ApiResponse<LeaderboardScoresPage> response;        try        {            response = await gameApiClient.Leaderboards.GetLeaderboardScoresAsync(ctx, ctx.ServiceToken, new Guid(ctx.ProjectId),                    leaderboardId, null, 5);            return response.Data.Results;        }        catch (ApiException e)        {            _logger.LogError("Failed to get top players for leaderboard: {LeaderboardId}. Error: {Error}", leaderboardId, e.Message);            throw new Exception($"Failed to get top players for leaderboard: {leaderboardId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

GetTopPlayers

関数を呼び出して、上位 5 人のプレイヤーのリストを取得します。レスポンスは以下のようになります。


{    "output": [        {            "playerId": "wYI5NW5gEVvR3PBmYXEzFS1JvSz3",            "playerName": "IncredibleGleamingPelican#3",            "rank": 0,            "score": 44.0        },        {            "playerId": "ryuAA3ZX23aRHN5ZJClC1Z5BrpVb",            "playerName": "EffectiveBindingBlackberry#9",            "rank": 1,            "score": 1.0        }    ]}

Lobby の使用

最初に、ロビーを作成する必要があります。現在ロビー内にいるプレイヤーのリストを取得し、その ID を使用してデータを操作できます。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.Lobby.Model;namespace CrossPlayerData;public class CrossPlayerData{    private readonly ILogger<CrossPlayerData> _logger;    public CrossPlayerData(ILogger<CrossPlayerData> logger)    {        _logger = logger;    }    [CloudCodeFunction("GetLobbyPlayers")]    public async Task<List<Player>> GetLobby(IExecutionContext ctx, IGameApiClient gameApiClient, string lobbyId)    {        ApiResponse<Lobby> response;        try        {            response = await gameApiClient.Lobby.GetLobbyAsync(ctx, ctx.ServiceToken, lobbyId, "cloud-code");            return response.Data.Players;        }        catch (ApiException e)        {            _logger.LogError("Failed to get players from lobby: {LobbyId}. Error: {Error}", lobbyId, e.Message);            throw new Exception ($"Failed to get players from lobby: {lobbyId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

GetLobbyPlayers

関数を呼び出して、ロビーにいるプレイヤーのリストを取得します。レスポンスは以下のようになります。


{    "output": [        {            "allocationId": null,            "connectionInfo": null,            "data": null,            "id": "Z96pNb4wfgdaMLqMQfWpwXEclaRR",            "joined": "2023-09-08T11:02:18.13Z",            "lastUpdated": "2023-09-08T11:02:18.13Z"        }    ]}

Friends の使用

Friends を使用するには、関係を作成する必要があります。詳細については、Friends のドキュメントを参照してください。

注

ヘルパーメソッド

SendFriendRequest

を使用して、プレイヤーに友達リクエストを送信できます。メソッドでは、

playerId

パラメーターを使用して、適切なユーザーにリクエストを送信します。

プレイヤーの友達のリストを取得し、その ID を使用してデータを操作できます。以下のサンプルは、プレイヤーが友達リクエストを送信したプレイヤー ID のリストを取得する方法を示します。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.Friends.Model;namespace CrossPlayerData;public class CrossPlayerData{    private readonly ILogger<CrossPlayerData> _logger;    public CrossPlayerData(IExecutionContext ctx, ILogger<CrossPlayerData> logger)    {        _logger = logger;    }    [CloudCodeFunction("SendFriendRequest")]    public async Task SendFriendRequest(IExecutionContext ctx, IGameApiClient gameApiClient, string playerId)    {        try        {            await gameApiClient.FriendsRelationshipsApi.CreateRelationshipAsync(                ctx, ctx.AccessToken, false, false, new AddRelationshipRequest(RelationshipType.FRIENDREQUEST, new List<MemberIdentity>                {                    new(id : playerId)                }));        }        catch (Exception e)        {            _logger.LogError("Failed to send a friend request to playerId: {playerId}. Error: {Error}", playerId, e.Message);            throw new Exception("Failed to send a friend request to playerId: " + playerId + ". Error: " + e.Message);        }    }    [CloudCodeFunction("GetRelationships")]    public async  Task<List<Relationship>> GetRelationships(IExecutionContext ctx, IGameApiClient gameApiClient)    {        try        {            var res = await gameApiClient.FriendsRelationshipsApi.GetRelationshipsAsync(ctx, ctx.AccessToken, 10, 0, false, false);            return res.Data;        }        catch (Exception e)        {            _logger.LogError("Failed to get relationships for playerId: {playerId}. Error: {Error}", ctx.PlayerId, e.Message);            throw new Exception("Failed to get relationships for playerId: " + ctx.PlayerId + ". Error: " + e.Message);        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

GetRelationships

関数を呼び出して、プレイヤーが友達リクエストを送信したプレイヤーのリストを取得します。レスポンスは以下のようになります。


{    "output": [        {            "created": "2023-09-18T14:46:34.74Z",            "expires": null,            "id": "5774e898-a078-4f92-9f0a-4c9beeb6d1bb",            "members": [                {                    "id": "0gvQingjjBwpZhkUJfeoKnFUkD4T"                }            ],            "type": "FRIEND_REQUEST"        }    ]}

プレイヤーデータの操作

プレイヤー ID のリストを入手したら、それらを使用して、UGS サービスを通じてプレイヤーデータを更新できます。以下のサンプルは、Cloud Save と Economy サービスを使用してプレイヤーデータを操作する方法を示します。

Cloud Code としての認証

クロスプレイヤーデータを操作するには、Cloud Code として認証する必要があります。Cloud Code として認証するには、モジュール関数内で

AccessToken

の代わりに

ServiceToken

を使用します。


await gameApiClient.CloudSaveData.SetItemAsync(ctx, ctx.ServiceToken, ctx.ProjectId, player.PlayerId, new SetItemBody("ReachedTop5", true));

認証で詳細情報を参照し、

ServiceToken

をサポートするサービスのリストについてはサービスとアクセストークンのサポートの説明を確認してください。

Cloud Save を使用した上位 5 人のプレイヤーデータの更新

プレイヤーデータを操作する 1 つの方法は、プレイヤー ID のリストを Cloud Save に渡すことです。サンプル内のモジュール関数は、リーダーボード ID をパラメーターとして受け取ります。以下のサンプルは、リーダーボードから取得した上位 5 人のプレイヤーのリストについて上位 5 人に到達するための値を Cloud Save に記録する方法を示します。サンプルが動作するためには、以下のステップに従います。

Leaderboards サービスを使用してリーダーボードを作成します。
リーダーボードに一部のプレイヤースコアを載せます。

新しいモジュールを作成し、以下のコードを追加します。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.CloudSave.Model;using Unity.Services.Leaderboards.Model;namespace CrossPlayerData;public class CrossPlayerData{    private readonly ILogger<CrossPlayerData> _logger;    public CrossPlayerData(ILogger<CrossPlayerData> logger)    {        _logger = logger;    }    [CloudCodeFunction("GetTopPlayers")]    public async Task<List<LeaderboardEntry>> GetTopPlayers(IExecutionContext ctx, IGameApiClient gameApiClient, string leaderboardId)    {        ApiResponse<LeaderboardScoresPage> response;        try        {            response = await gameApiClient.Leaderboards.GetLeaderboardScoresAsync(ctx, ctx.ServiceToken, new Guid(ctx.ProjectId),                    leaderboardId, null, 5);            return response.Data.Results;        }        catch (ApiException e)        {            _logger.LogError("Failed to get top players for leaderboard: {LeaderboardId}. Error: {Error}", leaderboardId, e.Message);            throw new Exception($"Failed to get top players for leaderboard: {leaderboardId}. Error: {e.Message}");        }    }    [CloudCodeFunction("UpdateTopPlayerData")]    public async Task UpdateTopPlayerData(IExecutionContext ctx, IGameApiClient gameApiClient, string leaderboardId)    {        var players = GetTopPlayers(ctx, gameApiClient, leaderboardId);        foreach (var player in players.Result)        {            try            {                await gameApiClient.CloudSaveData.SetItemAsync(ctx, ctx.ServiceToken, ctx.ProjectId, player.PlayerId, new SetItemBody("ReachedTop5", true));                _logger.LogInformation("Updated data for playerId {playerId}", player.PlayerId);            } catch (Exception e)            {                _logger.LogError("Failed to update data for playerId {playerId}. Error: {Error}", player.PlayerId, e.Message);                throw new Exception ($"Failed to update data for playerId: {player.PlayerId}. Error: {e.Message}");            }        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

UpdateTopPlayerData

関数は、リーダーボード内のすべてのプレイヤーのキーと値のペアを設定します。これを検証するために、Unity Cloud Dashboard で Player Management サービスに移動し、上位プレイヤーの Cloud Save データを調べることができます。

Economy を使用してロビー内のすべてのプレイヤーに報酬を与える

プレイヤーの残高を操作するには、プレイヤー ID のリストを Economy API に渡します。以下のサンプルは、ロビーから取得したプレイヤーのリストについて、通貨の残高を増やす方法を示します。モジュール関数は、ロビー ID、通貨 ID、および残高を増やす金額をパラメーターとして受け取ります。サンプルが動作するためには、以下のステップに従います。

Lobby サービスを使用してロビーを作成します。
ロビーにプレイヤーを配置します。
Economy サービスで通貨を作成および公開します。

新しいモジュールを作成し、以下のコードを追加します。


using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.Economy.Model;using Unity.Services.Lobby.Model;public class CrossPlayerData{    private readonly ILogger<CrossPlayerData> _logger;    public CrossPlayerData(ILogger<CrossPlayerData> logger)    {        _logger = logger;    }    [CloudCodeFunction("GetLobbyPlayers")]    public async Task<List<Player>> GetLobby(IExecutionContext ctx, IGameApiClient gameApiClient, string lobbyId)    {        ApiResponse<Lobby> response;        try        {            response = await gameApiClient.Lobby.GetLobbyAsync(ctx, ctx.ServiceToken, lobbyId, "cloud-code");            return response.Data.Players;        }        catch (Exception e)        {             _logger.LogError("Failed to get players from lobby: {LobbyId}. Error: {Error}", lobbyId, e.Message);            throw new Exception ($"Failed to get players from lobby: {lobbyId}. Error: {e.Message}");        }    }    [CloudCodeFunction("RewardLobbyPlayers")]    public async Task RewardLobbyPlayers(IExecutionContext ctx, IGameApiClient gameApiClient, string lobbyId, string currencyId, int amount)    {        var players = GetLobby(ctx, gameApiClient, lobbyId);        foreach (var player in players.Result)        {            try            {                await gameApiClient.EconomyCurrencies.IncrementPlayerCurrencyBalanceAsync(ctx, ctx.ServiceToken, ctx.ProjectId, player.Id, currencyId, new CurrencyModifyBalanceRequest(currencyId, amount));                _logger.LogInformation("Incremented balance for playerId {playerId} by {amount}", player.Id, amount);            } catch (Exception e)            {                _logger.LogError("Failed to increment {currencyId} balance for playerId {playerId}. Error: {Error}", currencyId, player.Id, e.Message);                throw new Exception($"Failed to increment {currencyId} balance for playerId {player.Id}. Error: {e.Message}");            }        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}

RewardLobbyPlayers

関数は、ロビー内のすべてのプレイヤーの通貨の残高を増やします。検証するために、Unity Cloud Dashboard で Player Management サービスに移動し、プレイヤーの残高を調べることができます。

ドキュメント

エンジン

サービス

Grow

産業

サポート

Cloud Code