Momentoリーダーボードの使用
Momento Leaderboardsは、専用のAPIを備えたトップクラスのサービスであり、数千万のアイテムを持つリーダーボードと、迅速な取り込み/照会/更新をサポートします。
リーダーボード・クライアントの方法
リーダーボードクライアントの作成
リーダーボードを作成し、操作するには、まずLeaderboardClientを作成 する必要があります。
パラメータ
configuration - LeaderboardConfiguration
- リーダーボードクライアントを設定するためのオプションです。詳細については、SDK Configuration Objects を参照してください。
credentialProvider - CredentialProvider
- Momento API キーの詳細については、Instantiating CredentialProviders を参照してください。
オプション・パラメータ
戻り値
新しいリーダーボードを作成し、既存のリーダーボードと相互作用することができる PreviewLeaderboardClient オブジェクト。
- JavaScript
- Go
new PreviewLeaderboardClient({
configuration: LeaderboardConfigurations.Laptop.v1(),
credentialProvider: CredentialProvider.fromEnvironmentVariable('MOMENTO_API_KEY'),
});
credentialProvider, err := auth.NewEnvMomentoTokenProvider("MOMENTO_API_KEY")
if err != nil {
panic(err)
}
leaderboardClient, err = momento.NewPreviewLeaderboardClient(
config.LeaderboardDefault(),
credentialProvider,
)
if err != nil {
panic(err)
}
リーダーボードの作成
LeaderboardClient を使用して、キャッシュとリーダーボード名を指定してリーダーボードを作成します。
パラメータ
cacheName - string
- どのキャッシュにリーダーボードを作成するか
leaderboardName - string
- リーダーボードの名前をどうするか
オプション・パラメータ
戻り値
リーダーボードオブジェクトまたはエラー
- JavaScript
- Go
// You can create multiple leaderboards using the same leaderboard client
// but with different cache and leaderboard names
leaderboardClient.leaderboard(cacheName, 'momento-leaderboard');
leaderboardClient.leaderboard(cacheName, 'acorns-leaderboard');
// Leaderboard and cache names must be non-empty strings
try {
leaderboardClient.leaderboard(cacheName, ' ');
} catch (error) {
console.log('Expected error creating a leaderboard with invalid leaderboard name:', error);
}
leaderboard, err = leaderboardClient.Leaderboard(ctx, &momento.LeaderboardRequest{
CacheName: cacheName,
LeaderboardName: "leaderboard",
})
if err != nil {
panic(err)
}
return leaderboard
リーダーボードの方法
要素のアップサート
リーダボードにまだ要素が存在しない場合、要素を挿入します。要素がすでにリーダーボードに存在する場合は、要素を更新します。。upsert呼び出しは成功するか失敗するかのどちらかです。
アップサートはバッチ操作として実装されているので、大規模なリーダーボードでは、最大8192要素のバッチでアップサートを行うことができます。
- JavaScript
// To upsert a large number of elements, you must upsert
// in batches of up to 8192 elements at a time.
// This example shows how to paginate for a large value of `totalNumElements`, such as `20000`.
const elements = [...Array(totalNumElements).keys()].map(i => {
return {id: i + 1, score: i * Math.random()};
});
for (let i = 0; i < totalNumElements; i += 8192) {
// Create a Map containing 8192 elements at a time
const batch = new Map(elements.slice(i, i + 8192).map(obj => [obj['id'], obj['score']]));
// Then upsert one batch at a time until all elements have been ingested
const result = await leaderboard.upsert(batch);
switch (result.type) {
case LeaderboardUpsertResponse.Success:
break;
case LeaderboardUpsertResponse.Error:
console.log(`Error upserting batch [${i}, ${i + 8192})`);
break;
}
}
パラメータ
elements - Dictionary
-
Dictionary of (id, score) pairs to upsert.
- id: integer
- score: double
-
idはプレイヤー識別子、セッション識別子、ブラウザ識別子、またはこのスコアボードに使いたい他の種類の識別子にすることができます。0から2^63-1まで、64ビットの符号なし整数で指定できます。
-
つま り、1人の選手が2つのIDを持っていない限り、2つのスコアを持つことはできません!
オプション・パラメータ
戻り値
以下のいずれか:
- JavaScript
- Go
// Upsert a set of elements as a Map
const elements1: Map<number, number> = new Map([
[123, 100.0],
[234, 200.0],
[345, 300.0],
[456, 400.0],
]);
const result1 = await leaderboard.upsert(elements1);
switch (result1.type) {
case LeaderboardUpsertResponse.Success:
console.log('Successfully upserted elements to leaderboard');
break;
case LeaderboardUpsertResponse.Error:
console.log('Upsert error:', result1.message());
throw new Error(
`An error occurred while attempting to call upsert on leaderboard 'momento-leaderboard' in cache '${cacheName}': ${result1.errorCode()}: ${result1.message()}`
);
}
// Or upsert a set of elements as a Record
const elements2: Record<number, number> = {
567: 500,
678: 600,
789: 700,
890: 800,
};
const result2 = await leaderboard.upsert(elements2);
switch (result2.type) {
case LeaderboardUpsertResponse.Success:
console.log('Successfully upserted elements to leaderboard');
break;
case LeaderboardUpsertResponse.Error:
console.log('Upsert error:', result2.message());
throw new Error(
`An error occurred while attempting to call upsert on leaderboard 'momento-leaderboard' in cache '${cacheName}': ${result2.errorCode()}: ${result2.message()}`
);
}
upsertElements := []momento.LeaderboardUpsertElement{
{Id: 123, Score: 10.33},
{Id: 456, Score: 3333},
{Id: 789, Score: 5678.9},
}
_, err := leaderboard.Upsert(ctx, momento.LeaderboardUpsertRequest{Elements: upsertElements})
if err != nil {
panic(err)
}
スコアで要素を取得
指定された最小スコアと最大スコアの範囲内にある要素を取得します。
同じスコアを持つ要素は、そのIDに基づいた英数字の順番で返されます(例えば、同じスコアを持つ要素のIDは、[1, 2, 10, 123, 2, 234, ...]
ではなく [1, 10, 123, 234, ...]
の順番で返されます)。
FetchByScoreはバッチ操作として実装されているので、大規模なリーダーボードでは、最大8192個の要素をバッチでフェッチすることができます。
offset
パラメータを使用すると、要求されたスコア範囲内にある複数の要素を、要求された要素の終わりを示す空のリストを受け取るまで、ページ送りすることができます。
- JavaScript
// Use the offset option to paginate through your results if your leaderboard
// has more than 8192 elements.
// This example shows how to paginate for a large value of `totalNumElements`, such as `20000`.
for (let offset = 0; offset < totalNumElements; offset += 8192) {
const result = await leaderboard.fetchByScore({offset});
switch (result.type) {
case LeaderboardFetchResponse.Success:
processBatch(result.values());
break;
case LeaderboardFetchResponse.Error:
console.log(
`Error fetching batch by score [${offset}, ${offset + 8192}) (${result.errorCode()}: ${result.message()})`
);
}
}
パラメータ
オプション・パラメータ
minScore - double
- スコア範囲の下限を含む。デフォルトは
-inf
です。
maxScore - double
- スコア範囲の排他的上限値。デフォルトは
+inf
です。
order - LeaderboardOrder enum
-
Enum values: Ascending, Descending
-
要素を取得する順番。デフォルトは昇順で、0が最も低いスコアとなります。
offset - integer
-
最初の要素を返す前にスキップする要素数。デフォルトは0。
-
Note: これは最初に返す要素のスコアではなく、最初の要素を返す前にスキップする結果セットの要素数です。
count - integer
- 返す要素の最大数。デフォルトは 8192 で、これはリクエストごとに取得できる最大数です。
戻り値
以下のいずれか:
- JavaScript
- Go
// By default, FetchByScore will fetch the elements from the entire score range
// with zero offset in ascending order. It can return 8192 elements at a time.
const result1 = await leaderboard.fetchByScore();
switch (result1.type) {
case LeaderboardFetchResponse.Success:
console.log('Successfully fetched elements using open score range:');
result1.values().forEach(element => {
console.log(`\tId: ${element.id} | Rank: ${element.rank} | Score: ${element.score}`);
});
break;
case LeaderboardFetchResponse.Error:
throw new Error(
`An error occurred while attempting to call fetchByScore with no options on leaderboard 'momento-leaderboard' in cache '${cacheName}': ${result1.errorCode()}: ${result1.message()}`
);
}
// Example specifying all FetchByScore options. You can provide any subset of these options
// to modify your FetchByScore request.
const result2 = await leaderboard.fetchByScore({
minScore: 10,
maxScore: 600,
order: LeaderboardOrder.Descending,
offset: 2,
count: 10,
});
switch (result2.type) {
case LeaderboardFetchResponse.Success:
console.log('Successfully fetched elements by score using all options:');
result2.values().forEach(element => {
console.log(`\tId: ${element.id} | Rank: ${element.rank} | Score: ${element.score}`);
});
break;
case LeaderboardFetchResponse.Error:
throw new Error(
`An error occurred while attempting to call fetchByScore with all options on leaderboard 'momento-leaderboard' in cache '${cacheName}': ${result2.errorCode()}: ${result2.message()}`
);
}
minScore := 150.0
maxScore := 3000.0
offset := uint32(1)
count := uint32(2)
fetchOrder := momento.ASCENDING
fetchByScoreResponse, err := leaderboard.FetchByScore(ctx, momento.LeaderboardFetchByScoreRequest{
MinScore: &minScore,
MaxScore: &maxScore,
Offset: &offset,
Count: &count,
Order: &fetchOrder,
})
if err != nil {
panic(err)
}
switch r := fetchByScoreResponse.(type) {
case *responses.LeaderboardFetchSuccess:
fmt.Printf("Successfully fetched elements by score:\n")
for _, element := range r.Values() {
fmt.Printf("ID: %d, Score: %f, Rank: %d\n", element.Id, element.Score, element.Rank)
}
}