GS2-Ranking SDK for Game Engine API リファレンス

モデル

EzCategoryModel

カテゴリーモデルカテゴリ毎に異なるランキングを作成できます。

カテゴリには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。ランキングを集計する際にスコアを小さいものを上位（昇順）にするか、大きいものを上位（降順）にするかを設定できます。

ランキングの種類として グローバル と スコープ を選択できます。グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。

グローバルランキングはカテゴリごとにランキングの集計間隔を15分～24時間で設定できます。スコープランキングはリアルタイムで集計結果が反映されます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

	型	必須	値の制限	説明
name	string	✓	~ 128文字	カテゴリ名
metadata	string		~ 1024文字	メタデータ
entryPeriodEventId	string		~ 1024文字	イベントGRN
accessPeriodEventId	string		~ 1024文字	イベントGRN

EzScore

スコア

ゲームプレイヤー毎×カテゴリ毎の登録されたスコアを保持するエンティティです。

	型	必須	デフォルト	値の制限	説明
categoryName	string	✓		~ 128文字	カテゴリ名
userId	string	✓		~ 128文字	ユーザーID
uniqueId	string	✓	UUID	~ 36文字	スコアのユニークID
scorerUserId	string	✓		~ 128文字	ユーザーID
score	long	✓		~ 9223372036854775806	スコア
metadata	string			~ 512文字	メタデータ

EzRanking

	型	必須	値の制限	説明
rank	long	✓	1 ~ 9223372036854775806	順位
index	long	✓	~ 9223372036854775806	1位からのインデックス
userId	string	✓	~ 128文字	ユーザーID
score	long	✓	~ 9223372036854775806	スコア
metadata	string		~ 512文字	メタデータ
createdAt	long	✓		作成日時

EzSubscribeUser

	型	必須	デフォルト	値の制限	説明
userId	string	✓		~ 128文字	ユーザーID
targetUserId	string	✓		~ 128文字	購読されるユーザID

メソッド

getCategory

カテゴリを取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名

Result

	型	説明
item	EzCategoryModel	カテゴリモデル

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->CategoryModel(
        "category-0001" // categoryName
    );
    const auto item = Domain.Model();

カテゴリの一覧を取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名

Result

	型	説明
items	List<EzCategoryModel>	カテゴリモデルのリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.CategoryModelsAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.CategoryModels(
    );
    List<EzCategoryModel> items = new List<EzCategoryModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->CategoryModels(
    );
    for (auto Item : *It)
    {

    }

listSubscribes

購読しているユーザIDの一覧を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
items	List<EzSubscribeUser>	購読対象のリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.SubscribeUsersAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.SubscribeUsers(
    );
    List<EzSubscribeUser> items = new List<EzSubscribeUser>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->SubscribeUsers( // categoryName
    );
    for (auto Item : *It)
    {

    }

ユーザIDを購読

ユーザIDを購読することで、そのユーザIDに関する新着メッセージ投稿の通知を受けることができます購読する際のオプションとして、「メッセージに付加されたカテゴリが特定の値のものだけ通知する」といった設定や「通知を受けたときにオフラインだった場合、モバイルプッシュ通知に転送する」といった設定ができます。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
targetUserId	string	✓	~ 128文字	購読するユーザーID

Result

	型	説明
item	EzSubscribeUser	購読した購読対象

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.SubscribeAsync(
        categoryName: "category-0001",
        targetUserId: "user-0002"
    );
    var item = await result.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.Subscribe(
        categoryName: "category-0001",
        targetUserId: "user-0002"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto Future = Domain->Subscribe(
        "category-0001",
        "user-0002"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

unsubscribe

購読の解除

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
targetUserId	string	✓	~ 128文字	購読解除するユーザーID

Result

	型	説明
item	EzSubscribeUser	解除した購読対象

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SubscribeUser(
        categoryName: "category-0001",
        targetUserId: "user-0002"
    );
    var result = await domain.UnsubscribeAsync(
    );

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).SubscribeUser(
        categoryName: "category-0001",
        targetUserId: "user-0002"
    );
    var future = domain.Unsubscribe(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->SubscribeUser(
        "category-0001", // categoryName
        "user-0002" // targetUserId
    );
    const auto Future = Domain->Unsubscribe(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getNearRanking

指定したスコア付近のランキングを取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
score	long	✓	~ 9223372036854775806	スコア

Result

	型	説明
items	List<EzRanking>	ランキングのリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    );
    var items = await domain.NearRankingsAsync(,
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    );
    var it = domain.NearRankings(,
    );
    List<EzRanking> items = new List<EzRanking>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    );
    const auto It = Domain->NearRankings(, // categoryName // score
    );
    for (auto Item : *It)
    {

    }

getRank

順位を取得

ユーザID毎にスコアを1つしか登録できないカテゴリを指定する場合、ユニークIDは省略可能です

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
scorerUserId	string	✓		~ 128文字	スコアを獲得したユーザーのユーザーID
accessToken	string	✓		~ 128文字	ランキングを取得するユーザーID（GS2-Schedule の期間判定に使用されます。）
uniqueId	string	✓	“0”	~ 36文字	スコアのユニークID

Result

	型	説明
item	EzRanking	ランキング

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ranking(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync(
        scorerUserId : "user-0001"
    );

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ranking(
        categoryName: "category-0001"
    );
    var future = domain.Model(
        scorerUserId : "user-0001"
    );
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Ranking(
        "category-0001" // categoryName
    );
    const auto item = Domain.ModelAsync(
        "user-0001" // scorerUserId
    );

getRanking

ランキングを取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
accessToken	string			~ 128文字	ユーザーID
limit	int	✓	30	1 ~ 1000	データの取得件数
pageToken	string			~ 4096文字	データの取得を開始する位置を指定するトークン
startIndex	long			~ 9223372036854775806	ランキングの取得を開始するインデックス

Result

	型	説明
items	List<EzRanking>	ランキングのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.RankingsAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Rankings(
    );
    List<EzRanking> items = new List<EzRanking>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Rankings( // categoryName
    );
    for (auto Item : *It)
    {

    }

putScore

スコアを登録

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
score	long	✓	~ 9223372036854775806	スコア
metadata	string		~ 512文字	メタデータ

Result

	型	説明
item	EzScore	登録したスコア

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ranking(
        categoryName: "category-0001"
    );
    var result = await domain.PutScoreAsync(
        score: 1000L,
        metadata: null
    );
    var item = await result.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ranking(
        categoryName: "category-0001"
    );
    var future = domain.PutScore(
        score: 1000L,
        metadata: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Ranking(
        "category-0001" // categoryName
    );
    const auto Future = Domain->PutScore(
        1000L,
        nullptr // metadata
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

getScore

ゲームプレイヤーが登録したスコアを取得

ユーザID毎にスコアを1つしか登録できないカテゴリを指定する場合、ユニークIDは省略可能です

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
accessToken	string	✓		~ 128文字	ユーザーID
scorerUserId	string	✓		~ 128文字	ユーザーID
uniqueId	string	✓	“0”	~ 36文字	スコアのユニークID

Result

	型	説明
item	EzScore	スコア

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Score(
        "category-0001", // categoryName
        "user-0002", // scorerUserId
        "unique-0001" // uniqueId
    );
    const auto item = Domain.Model();

listScores

ゲームプレイヤーが登録したスコアの一覧を取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
scorerUserId	string	✓		~ 128文字	ユーザーID
accessToken	string	✓		~ 128文字	ユーザーID
limit	int	✓	30	1 ~ 1000	データの取得件数
pageToken	string			~ 1024文字	データの取得を開始する位置を指定するトークン

Result

	型	説明
items	List<EzScore>	スコアのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ScoresAsync(,
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Scores(,
    );
    List<EzScore> items = new List<EzScore>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Scores(, // categoryName // scorerUserId
    );
    for (auto Item : *It)
    {

    }

GS2-Ranking SDK for Game Engine API リファレンス

モデル

EzCategoryModel

EzScore

EzRanking

EzSubscribeUser

メソッド

getCategory

Request

Result

実装例

listCategories

Request

Result

実装例

listSubscribes

Request

Result

実装例

subscribe

Request

Result

実装例

unsubscribe

Request

Result

実装例

getNearRanking

Request

Result

実装例

getRank

Request

Result

実装例

getRanking

Request

Result

実装例

putScore

Request

Result

実装例

getScore

Request

Result

実装例

listScores

Request

Result

実装例