Fehlercodes und Grenzwerte von Datenspeichern

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

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

Fehlercode-Referenz

Serverfehlercodes

Grenzen

Datenmodelle haben Grenzen. Wenn eine Erfahrung diese Grenzen überschreitet, drosselt der Dienst automatisch die Nutzung des Datenspeichers der Erfahrung und sorgt dafür, dass zukünftige Anfragen in eine der folgenden Warteschlangen eingeordnet werden:

• Set
• Geordnetes Set
• Get
• Geordnetes Get

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

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

Zugriffslimits

Datenspeicher unterliegen sowohl Erfahrungs- als auch Server-Limits. Die Erfahrungs-Limits skalieren mit der Gesamtanzahl der gleichzeitigen Benutzer in der Erfahrung, während die Server-Limits konfigurierbar sind und als Werkzeug für den Ersteller gedacht sind.

Erfahrungs-Limits

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

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

Standarddatenspeicher

Geordnete Datenspeicher

Steuerung von Ratenlimits

Da Open Cloud- und Spielserveranfragen geteilt werden, ist es wichtig, unabhängig zu steuern, wie viel jeder davon verbrauchen kann.

Spielserver

Einzelne Server haben integrierte Limits, wie oben beschrieben. Verwenden Sie eine Kombination aus SetRateLimitForRequestType() und GetRequestBudgetForRequestType(), um eine präzise Kontrolle über den Beitrag der einzelnen Server zum Gesamthaushalt zu erhalten.

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 Verzögerung hinzu, insbesondere wenn Sie in einer kontinuierlichen Schleife dieselbe API aufrufen. Setzen Sie diese Verzögerung auf 60 / (gewünschter Budgetverbrauch pro Minute) Sekunden, als obere Grenze. Beachten Sie, dass dieser Ansatz keine Anfragen in Spitzenzeiten 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/';

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

// Obergrenzenabstand 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 das Intervall dieser Operation, bevor es zurückkehrt.
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 ein String 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('Es trat ein Fehler während der Ausführung auf:', error);
    }
})();

Serverlimits

Jeder Server hat ein konfigurierbares Ratenlimit für jeden Anfrage-Typ, basierend auf der Anzahl der Spieler auf diesem Server. Server erhalten beim ersten Start einen einmaligen Anstieg des zusätzlichen Anfragebudgets. Verwenden Sie GetRequestBudgetForRequestType(), um die Anzahl der Datenspeicheranfragen zu bestätigen, die der aktuelle Server zu einem beliebigen Zeitpunkt durchführen kann.

Diese Limits sind konfigurierbar durch den Ersteller mit der SetRateLimitForRequestType() API. Mit dieser API kann ein Ersteller die Ratenlimits seiner eigenen Datenspeicher für jeden Anfrage-Typ konfigurieren.

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

Standarddatenspeicher

Geordnete Datenspeicher

Datenlimits

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

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

Die Daten (Schlüsselwert) werden auch als String 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 von Zeichen in benutzerdefinierten Metadaten.

Durchsatzlimits

Pro-Schlüssel-Durchsatzlimits 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 erfrischt sich im Laufe der Zeit.

Roblox untersucht die Nutzung des mit dem Schlüssel verbundenen Kontingents über die 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.

Neben 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 weiterer 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 standardmäßige Datenspeicher.

Speicherlimits

Um die Speicherung stabil und skalierbar zu halten, nutzen Datenspeicher ein spielbasiertes Limit für Ihre Speichernutzung.

Dieses Limit besteht aus einer Grundzuweisung für jedes Spiel plus einer zusätzlichen Zuweisung basierend auf der Anzahl der Lebensnutzer. Ein Lebensnutzer 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 × Lebensbenutzeranzahl.

Die Speichernutzung wird anhand der komprimierten Größe der neuesten Version jedes Schlüssels gemessen. Datenspeicher komprimieren Ihre Daten automatisch vor der Speicherung, also vermeiden Sie es, sie selbst vorab zu komprimieren. Die Vorabkomprimierung erhöht die unnötige CPU-Last und kann die Effektivität der integrierten Kompression von Datenspeichern verringern. Indem Sie unkomprimierte Daten speichern, profitieren Sie automatisch von Verbesserungen der Kompressionsalgorithmen 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 DeleteDataStore Methode gelöscht wurden, zählen jedoch während ihrer 30-tägigen Löschbearbeitungszeit weiterhin zur Speichernutzung, bis sie dauerhaft entfernt werden.