データストアのエラーコードと制限

データストアへのリクエストは、接続性の低下やその他の問題により失敗することがあります。エラーを処理し、エラーコードを含むメッセージを返すには、データストア関数を pcall() でラップします。

UpdateAsync() のような失敗した書き込み呼び出しは、ゲームサーバーが成功した応答を受け取らなかったことを意味します。これは、バックエンドの書き込みが行われなかったことを常に保証するものではありません。いくつかの失敗シナリオでは、最終的な書き込み状態はキャッシュなしでフォローアップの読み取りを行うまで呼び出し元には不明なままです。

エラーコードリファレンス

サーバーエラーコード

制限

データモデルには制限があります。体験がこれらの制限を超えると、サービスは自動的に体験のデータストアの使用をスロットリングし、今後のリクエストを次のいずれかのキューに置きます：

• セット
• 古いセット
• 取得
• 古い取得

キュー内のリクエストは、受信した順に処理されます。呼び出された関数は、リクエストがまだキューにある限り、引き続き待機します。データストアキー自体がスロットリングされている場合、リクエストはキューに置かれますが、一時的にスキップされます。

各キューの制限は30リクエストです。キューの制限に達すると、リクエストは301-306の範囲内のエラーコードで失敗し、リクエストが完全にドロップされたことを示します。

アクセス制限

データストアには経験とサーバーレベルの制限の両方が適用されます。経験レベルの制限は、体験全体の同時ユーザー数に応じてスケールしますが、サーバーレベルの制限は構成可能で、クリエイターがツールとして使用することを目的としています。

経験制限

各体験には、データストアの種類、リクエストの種類、および同時ユーザー数に基づいて、一定数のデータストアリクエストが許可されています。各データストアタイプおよびリクエストタイプに対する制限は、すべてのリストされた関数の間で共有されます。

• UpdateAsync()は、読み取りおよび書き込みリクエスト予算の両方から消費されます。1回の呼び出しで両方の制限が減少します。
• ゲームサーバーとオープンクラウドは共有予算を持っています。オープンクラウドのトラフィックは、体験内での使用によってスロットリングされる可能性があります（その逆も同様です）。詳細なガイダンスについては、制御率制限を参照してください。

標準データストア

順序付きデータストア

制御率制限

オープンクラウドとゲームサーバーのリクエストは共有されるため、それぞれが予算からどれだけ消費できるかを独立して制御することが重要です。

ゲームサーバー

個々のサーバーには、上記のように組み込みの制限があります。SetRateLimitForRequestType()とGetRequestBudgetForRequestType()を組み合わせて、個々のサーバーの総予算への貢献を詳細に制御できます。

オープンクラウド

オープンクラウドリクエストは、外部のレート制限ソリューションを必要とします。以下のアプローチのいずれかを推奨します：

• （シンプル）特に、同じAPIを連続ループで呼び出す場合、各リクエストの後に短いタイムアウトを追加します。このタイムアウトは、60 / (1分あたりの希望する予算消費)の秒数と等しくすることで上限を設定します。このアプローチは、一度にリクエストをバーストして送信することを許可しないことに注意してください。
• （堅牢）漏れバケット戦略を使用したローカルレートリミッターを実装します。

以下のNode.jsコードサンプルには、参照実装が含まれています。

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('API_KEYの環境変数が設定されていません。');
}

const apiHeaderKey = 'x-api-key';

const universeId = '';
const dataStoreId = 'Inventory';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

// --- 操作ごとのレート制限設定（1分あたりのリクエスト数） ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// 操作ごとの上限間隔：60 / (1分あたりのリクエスト数)秒。
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// リクエストを実行し、この操作の自身の間隔を待ってから返す。
async function throttledFetch(url, options, intervalMs) {
    const response = await fetch(url, options);
    await sleep(intervalMs);
    return response;
}

async function listEntries(universe, dataStore) {
    const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
    const url = baseUrl + listPath;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, LIST_INTERVAL_MS);
    return response.json();
}

async function getEntry(path) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, GET_INTERVAL_MS);
    return response.json();
}

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // ボディは文字列でなければなりません
    }, UPDATE_INTERVAL_MS);
    return response;
}

(async () => {
    try {
        const entries = await listEntries(universeId, dataStoreId);

        for (const entry of entries.dataStoreEntries) {
            const path = entry.path;
            console.log(`\nエントリを処理中: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`ステータス: ${updateResponse.status}`);
            console.log(`応答: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('実行中にエラーが発生しました:', error);
    }
})();

サーバー制限

各サーバーには、そのサーバー内のプレイヤー数に基づいたリクエストタイプごとの構成可能なレート制限があります。サーバーは、最初に作成されるときに追加のリクエスト予算のスタートアップバーストを受け取ります。現在のサーバーがいつでも行えるデータストアリクエストの数を確認するには、GetRequestBudgetForRequestType()を使用します。

これらの制限は、クリエイターがSetRateLimitForRequestType() APIを使用して構成可能です。このAPIを使用することで、クリエイターは各リクエストタイプに対して独自のデータストアのレート制限を設定できます。

APIが呼び出されない場合、次のデフォルトレート制限が適用されます：

標準データストア

順序付きデータストア

データ制限

データストアは、エントリごとに使用できるデータ量を制限します。

データストア名、キー名、スコープは、すべて一定の文字数以下でなければなりません。string.len()を使用してその長さを確認できます。

データ（キー値）も、その初期タイプに関係なく文字列として保持されます。データのサイズを確認するには、Luauデータをシリアル化されたJSONテーブルに変換するJSONEncode()関数を使用できます。

メタデータ制限

ユーザー定義メタデータの文字数制限。

スループット制限

キーごとのスループット制限は、Robloxサーバーでのパフォーマンスを最適に保つために設定されています。各制限は、体験全体のすべてのキーに適用され、時間とともにリフレッシュされます。

Robloxは、最後の60秒間におけるキーに関連した割り当ての使用状況を調査します。使用量がスループット制限内にある場合、リクエストは承認されます。もし使用量が制限を超えた場合、リクエストは拒否されます。

上記のスループット制限に加えて、Robloxは内部スキーマに基づいてデータをパーティションに整理します。そのため、バックエンドサーバーが同じデータストアへのリクエストの大量を受信する場合、さらなるスロットリングが発生する可能性があります。原因に関係なく、スロットリングは、スループット制限が単一のデータストアまたはキーに対して超えられたかどうかに基づいて、DatastoreThrottledまたはKeyThrottledエラーとして現れます。これらのエラーメッセージは、順序付きデータストアと標準データストアの両方に適用されます。

ストレージ制限

ストレージを安定させ、スケーラブルに保つために、データストアはストレージ使用量に対するゲームレベルの制限を使用します。

この制限は、各ゲームに対する基本的な割り当てと、ライフタイムユーザーの数に基づく追加の割り当てで構成されています。ライフタイムユーザーとは、あなたのゲームに少なくとも一度参加したすべてのユーザーを指します。

ストレージ制限は、次の式を使用して計算されます 最新のバージョンのストレージ制限合計 = 500 MB + 1 MB × ライフタイムユーザー数。

ストレージ使用量は、各キーの最新バージョンの圧縮サイズを使用して測定されます。データストアはストレージの前に自動的にデータを圧縮するため、自分で事前に圧縮することを避けてください。事前圧縮は不必要なCPUオーバーヘッドを追加し、データストアの標準の圧縮の有効性を低下させる可能性があります。非圧縮データを保存することにより、Robloxの圧縮アルゴリズムと将来のスキーマベースの最適化の改善の恩恵を自動的に受けることができます。

各キーの最新バージョンのみがストレージ使用量にカウントされます。削除されたキーや廃止されたバージョンは、保存期間中にバージョンAPIを介してアクセス可能ですが、ストレージ使用量にはカウントされません。ただし、Open CloudのDeleteDataStoreメソッドを介して削除されたデータストアは、30日間の削除処理期間中はストレージ使用量にカウントされ続け、永久に削除されるまでカウントされます。