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

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

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

エラーコードの参照

サーバーエラーコード

制限

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

• セット
• 順序付きセット
• 取得
• 順序付き取得

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

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

アクセス制限

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

体験制限

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

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

標準データストア

順序付きデータストア

レート制限の制御

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

ゲームサーバー

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

オープンクラウド

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

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

以下の 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/';

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

// 操作ごとの上限間隔: 60 / (リクエスト数/分) 秒。
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 が呼び出されない場合、以下の デフォルトのレート制限 が適用されます。

標準データストア

順序付きデータストア

データ制限

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

データストア名、キー名、および スコープ はすべて特定の文字数制限内でなければなりません。string.len() を使用してその長さを確認してください。

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

メタデータ制限

ユーザー定義メタデータの文字数に対する制限。

スループット制限

キーごとのスループット制限は、Roblox サーバーでのパフォーマンスが最適であることを保証します。各制限は、体験内のすべてのサーバーにわたってすべてのキーに適用され、時間とともにリフレッシュされます。

Roblox は、キーに関連付けられたクォータの使用状況を過去60秒間調べます。使用状況がスループット制限内であれば、リクエストは承認されます。使用状況が制限を超えると、リクエストは拒否されます。

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

ストレージ制限

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

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

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

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

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