Fehlercodes und Limits für Datenspeicher

Anfragen, die Sie an Datenspeicher stellen, können aufgrund schlechter Konnektivität oder anderer Probleme fehlschlagen. Um Fehler zu behandeln und Nachrichten mit einem Fehlercode zurückzugeben, wickeln Sie Datenspeicherfunktionen in pcall() ein.

Ein fehlgeschlagener Schreibaufruf, wie UpdateAsync(), bedeutet, dass der Spieleserver keine erfolgreiche Antwort erhalten hat. Es garantiert nicht immer, dass der Backend-Schreibvorgang nicht stattgefunden hat. In einigen Fehlerszenarien kann der endgültige Schreibstatus dem Aufrufer unbekannt sein, bis er mit einem nachfolgenden Lesevorgang ohne Cache überprüft wird.

Fehlercode-Referenz

Serverfehlercodes

Limits

Datenmodelle haben Limits. Wenn eine Erfahrung diese Limits überschreitet, drosselt der Dienst automatisch die Nutzung des Datenspeichers der Erfahrung und verursacht, dass zukünftige Anfragen in eine der folgenden Warteschlangen gestellt werden:

• Setzen
• Geordnetes Setzen
• Holen
• Geordnetes Holen

Anfragen in einer Warteschlange werden in der Reihenfolge bearbeitet, in der sie empfangen wurden. Die aufgerufene Funktion gibt weiterhin nach, solange ihre Anfrage noch in der Warteschlange ist. Wenn der Datenspeicherschlüssel selbst gedrosselt wird, wird die Anfrage in eine Warteschlange gestellt, aber vorübergehend übersprungen.

Jede Warteschlange hat ein Limit von 30 Anfragen. Wenn das Limit einer Warteschlange erreicht ist, schlagen Anfragen mit einem Fehlercode im Bereich von 301-306 fehl, was darauf hinweist, dass die Anfragen vollständig abgelehnt wurden.

Zugriffslimits

Datenspeicher unterliegen sowohl Erfahrungs- als auch serverseitigen Limits. Die Limits auf Erfahrungsebene skalieren mit der Gesamtzahl der gleichzeitigen Benutzer in der Erfahrung, während die serverseitigen Limits konfigurierbar sind und als Werkzeug vom Ersteller verwendet werden sollen.

Erfahrungsgrenzen

Jede Erfahrung darf eine bestimmte Anzahl von Datenspeicheranfragen basierend auf dem Datenspeichertyp, dem Anfragetyp und der Anzahl der gleichzeitigen Benutzer haben. Für jeden Datenspeichertyp und Anfragetyp wird das Limit unter allen aufgeführten Funktionen geteilt.

• UpdateAsync() verbraucht sowohl das Lese- als auch das Schreibbudget. Ein einzelner Aufruf verringert beide Limits.
• Spieleserver und Open Cloud teilen ein Budget; Open Cloud-Verkehr kann durch die Nutzung innerhalb der Erfahrung gedrosselt werden (und umgekehrt). Siehe Kontrollieren Sie die Ratenlimits für weitere Hinweise.

Standard-Datenspeicher

Geordnete Datenspeicher

Kontrollieren Sie die Ratenlimits

Da Open Cloud- und Spieleserveranfragen geteilt werden, ist es wichtig, unabhängig zu steuern, wie viel jeder aus dem Budget verbrauchen kann.

Spieleserver

Einzelne Server haben eingebaute Limits, wie oben beschrieben. Verwenden Sie eine Kombination aus SetRateLimitForRequestType() und GetRequestBudgetForRequestType(), um eine feinkörnige Kontrolle über den Beitrag einzelner Server zum Gesamtbudget aufrechtzuerhalten.

Open Cloud

Open Cloud-Anfragen erfordern eine externe Ratenbegrenzungslösung. Wir empfehlen einen der folgenden Ansätze:

• (Einfach) Fügen Sie nach jeder Anfrage eine kurze Wartezeit hinzu, insbesondere wenn Sie dieselbe API in einer kontinuierlichen Schleife aufrufen. Setzen Sie diese Wartezeit auf 60 / (gewünschter Budgetverbrauch pro Minute) Sekunden als obere Grenze. Beachten Sie, dass dieser Ansatz keine Anfragen in Stößen zulässt.
• (Robust) Implementieren Sie einen lokalen Ratenbegrenzer mit der Leaky-Bucket-Strategie.

Die folgenden Node.js-Codebeispiele enthalten Referenzimplementierungen.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('Die Umgebungsvariable API_KEY ist nicht gesetzt.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Ratenbegrenzung pro Operation (Anfragen pro Minute) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Obergrenze für den Abstand pro Operation: 60 / (Anfragen pro Minute) Sekunden.
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));

// Führt die Anfrage aus und wartet dann auf den eigenen Intervall dieser Operation, bevor sie zurückgegeben wird.
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) // Der Body muss eine Zeichenfolge sein
    }, 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(`\nVerarbeite Eintrag: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Status: ${updateResponse.status}`);
            console.log(`Antwort: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Ein Fehler ist während der Ausführung aufgetreten:', error);
    }
})();

Serverlimits

Jeder Server hat ein konfigurierbares Ratenlimit für jeden Anfragetyp, basierend auf der Anzahl der Spieler in diesem Server. Server erhalten einen einmaligen Start-Burst von zusätzlichem Anfragebudget, wenn sie zum ersten Mal erstellt werden. Verwenden Sie GetRequestBudgetForRequestType(), um die Anzahl der Datenspeicheranfragen zu bestätigen, die der aktuelle Server zu einem bestimmten Zeitpunkt stellen kann.

Diese Limits sind konfigurierbar durch den Ersteller mithilfe der SetRateLimitForRequestType()-API. Mit dieser API kann ein Ersteller seine eigenen Ratenlimits für Datenspeicher für jeden Anfragetyp konfigurieren.

Die folgenden Standard-Ratenlimits gelten, wenn die API nicht aufgerufen wird:

Standard-Datenspeicher

Geordnete Datenspeicher

Datenlimits

Datenspeicher begrenzen, wie viele Daten pro Eintrag verwendet werden können.

Der Name des Datenspeichers, der Schlüsselname und der Bereich müssen alle eine bestimmte Zeichenlänge unterschreiten. Verwenden Sie string.len(), um ihre Länge zu überprüfen.

Die Daten (Schlüsselwert) werden ebenfalls als Zeichenfolge gespeichert, unabhängig von ihrem ursprünglichen Typ. Sie können die Größe der Daten mit der Funktion JSONEncode() überprüfen, die Luau-Daten in eine serialisierte JSON-Tabelle umwandelt.

Metadatenlimits

Limits für die Anzahl der Zeichen in benutzerdefinierten Metadaten.

Durchsatzlimits

Durchsatzlimits pro Schlüssel stellen sicher, dass die Leistung auf Roblox-Servern optimal ist. Jedes Limit gilt für jeden einzelnen Schlüssel über alle Server in einer Erfahrung und wird im Laufe der Zeit zurückgesetzt.

Roblox untersucht die Nutzung des mit dem Schlüssel verbundenen Kontingents in den letzten 60 Sekunden. Wenn die Nutzung, einschließlich der aktuellen Anfrage, innerhalb des Durchsatzlimits liegt, wird die Anfrage genehmigt. Wenn die Nutzung das Limit überschreitet, wird die Anfrage abgelehnt.

Zusätzlich zu den oben genannten Durchsatzlimits organisiert Roblox Daten in Partitionen basierend auf einem internen Schema. Wenn der Backend-Server daher ein hohes Volumen an Anfragen an denselben Datenspeicher erhält, kann dies zu einer weiteren Drosselung führen. Unabhängig von der Ursache manifestiert sich die Drosselung entweder als DatastoreThrottled- oder KeyThrottled-Fehler, je nachdem, ob das Durchsatzlimit für einen einzelnen Datenspeicher oder einen Schlüssel überschritten wurde. Diese Fehlermeldungen gelten sowohl für geordnete als auch für Standard-Datenspeicher.

Speicherlimits

Um den Speicher stabil und skalierbar zu halten, verwenden Datenspeicher ein spielübergreifendes Limit für Ihre Speichernutzung.

Dieses Limit besteht aus einer Basiszuweisung für jedes Spiel plus einer zusätzlichen Zuweisung basierend auf der Anzahl der Lebenszeitbenutzer. Ein Lebenszeitbenutzer ist jeder Benutzer, der Ihr Spiel mindestens einmal betreten hat.

Das Speicherlimit wird mit der folgenden Formel berechnet: Gesamtes Speicherlimit der neuesten Version = 500 MB + 1 MB × Anzahl der Lebenszeitbenutzer.

Die Speichernutzung wird anhand der komprimierten Größe der neuesten Version jedes Schlüssels gemessen. Datenspeicher komprimieren Ihre Daten automatisch vor der Speicherung, daher sollten Sie vermeiden, sie selbst vorab zu komprimieren. Die Vorabkomprimierung fügt unnötige CPU-Überlastung hinzu und kann die Effektivität der integrierten Komprimierung von Datenspeichern verringern. Durch die Speicherung unkomprimierter Daten profitieren Sie automatisch von Verbesserungen der Komprimierungsalgorithmen von Roblox und zukünftigen schema-basierten Optimierungen.

Nur die neueste Version jedes Schlüssels zählt zu Ihrer Speichernutzung. Gelöschte Schlüssel und überholte Versionen, die während ihrer Aufbewahrungsfrist weiterhin über die Versions-APIs zugänglich sind, zählen nicht zu Ihrer Speichernutzung. Datenspeicher, die über die Open Cloud-Methode DeleteDataStore gelöscht wurden, zählen jedoch weiterhin während ihrer 30-tägigen Löschverarbeitungsperiode zu Ihrer Speichernutzung, bis sie dauerhaft entfernt werden.