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
実装例
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();
listCategories
カテゴリの一覧を取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
Result
実装例
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
実装例
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)
{
}
subscribe
ユーザIDを購読
ユーザIDを購読することで、そのユーザIDに関する新着メッセージ投稿の通知を受けることができます
購読する際のオプションとして、「メッセージに付加されたカテゴリが特定の値のものだけ通知する」といった設定や
「通知を受けたときにオフラインだった場合、モバイルプッシュ通知に転送する」といった設定ができます。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
categoryName | string | ✓ | | ~ 128文字 | カテゴリ名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
targetUserId | string | ✓ | | ~ 128文字 | 購読するユーザーID |
Result
実装例
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
実装例
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
実装例
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
実装例
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
実装例
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
実装例
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
実装例
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)
{
}