Kody błędów i limity magazynu danych

Żądania, które wysyłasz do magazynów danych, mogą nie powieść się z powodu słabej łączności lub innych problemów. Aby obsłużyć błędy i zwrócić komunikaty z kodem błędu, owiń funkcje magazynu danych w pcall().

Nieudane wywołanie zapisu, takie jak UpdateAsync(), oznacza, że serwer gry nie otrzymał pomyślnej odpowiedzi. Nie zawsze gwarantuje to, że zapis w zapleczu nie miał miejsca. W niektórych scenariuszach awarii, ostateczny stan zapisu może być nieznany dla wywołującego, dopóki nie zostanie zweryfikowany za pomocą kolejnego odczytu bez pamięci podręcznej.

Odniesienie do kodów błędów

Kody błędów serwera

Limity

Modele danych mają limity. Jeśli doświadczenie przekroczy te limity, usługa automatycznie ogranicza użycie magazynu danych doświadczenia i powoduje, że przyszłe żądania są umieszczane w jednej z następujących kolejek:

• Ustaw
• Zamówione ustawienie
• Odczyt
• Zamówiony odczyt

Żądania w kolejce są obsługiwane w kolejności, w jakiej zostały odebrane. Wywołana funkcja nadal będzie czekać, dopóki jej żądanie jest nadal w kolejce. Jeśli klucz magazynu danych jest ograniczony, żądanie jest umieszczane w kolejce, ale jest tymczasowo pomijane.

Każda kolejka ma limit 30 żądań. Gdy limit kolejki zostanie osiągnięty, żądania kończą się niepowodzeniem z kodem błędu w zakresie 301-306, co wskazuje, że żądania zostały całkowicie odrzucone.

Limity dostępu

Magazyny danych podlegają zarówno limitem doświadczenia, jak i serwera. Limity na poziomie doświadczenia skalują się w zależności od całkowitej liczby jednoczesnych użytkowników w doświadczeniu, podczas gdy limity na poziomie serwera są konfigurowalne i mają być używane jako narzędzie przez twórcę.

Limity doświadczenia

Każde doświadczenie ma dozwoloną określoną liczbę żądań magazynu danych w zależności od typu magazynu danych, typu żądania i liczby jednoczesnych użytkowników. Dla każdego typu magazynu danych i typu żądania limit jest dzielony między wszystkie wymienione funkcje.

• UpdateAsync() zużywa zarówno budżet żądań odczytu, jak i zapisu. Pojedyncze wywołanie zmniejszy oba limity.
• Serwer gry i Open Cloud dzielą budżet; ruch Open Cloud może być ograniczany przez użycie w doświadczeniu (i odwrotnie). Zobacz Kontroluj limity przepustowości w celu uzyskania dalszych wskazówek.

Standardowe magazyny danych

Zamówione magazyny danych

Kontroluj limity przepustowości

Ponieważ żądania Open Cloud i serwera gry są współdzielone, ważne jest, aby niezależnie kontrolować, ile każde z nich może zużywać z budżetu.

Serwer gry

Poszczególne serwery mają wbudowane limity, jak opisano powyżej. Użyj kombinacji SetRateLimitForRequestType() i GetRequestBudgetForRequestType(), aby utrzymać szczegółową kontrolę nad wkładem poszczególnych serwerów w całkowity budżet.

Open Cloud

Żądania Open Cloud wymagają zewnętrznego rozwiązania do ograniczania przepustowości. Zalecamy jedno z następujących podejść:

• (Proste) Dodaj krótki czas oczekiwania po każdym żądaniu, szczególnie jeśli wywołujesz to samo API w ciągłej pętli. Ustaw ten czas oczekiwania równy 60 / (pożądana konsumpcja budżetu na minutę) sekund, jako górną granicę. Zauważ, że to podejście nie pozwala na wysyłanie żądań w wybuchach.
• (Solidne) Zaimplementuj lokalny ogranicznik przepustowości, korzystając ze strategii leaky bucket.

Poniższe przykłady kodu Node.js zawierają implementacje referencyjne.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('Zmienna środowiskowa API_KEY nie jest ustawiona.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Konfiguracja ograniczania przepustowości na operację (żądania na minutę) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Górna granica odstępu na operację: 60 / (żądania na minutę) sekundy.
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));

// Wykonuje żądanie, a następnie czeka na własny odstęp tej operacji przed zwróceniem.
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) // Ciało musi być ciągiem
    }, 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(`\nPrzetwarzanie wpisu: ${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(`Odpowiedź: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Wystąpił błąd podczas wykonywania:', error);
    }
})();

Limity serwera

Każdy serwer ma konfigurowalny limit przepustowości dla każdego typu żądania, w zależności od liczby graczy na tym serwerze. Serwery otrzymują jednorazowy wybuch dodatkowego budżetu żądań, gdy są po raz pierwszy tworzone. Użyj GetRequestBudgetForRequestType(), aby potwierdzić liczbę żądań magazynu danych, które bieżący serwer może wykonać w danym momencie.

Te limity są konfigurowalne przez twórcę za pomocą API SetRateLimitForRequestType(). Używając tego API, twórca może skonfigurować własne limity przepustowości magazynów danych dla każdego typu żądania.

Poniższe domyślne limity przepustowości mają zastosowanie, jeśli API nie jest wywoływane:

Standardowe magazyny danych

Zamówione magazyny danych

Limity danych

Magazyny danych ograniczają, ile danych można używać na wpis.

Nazwa magazynu danych, nazwa klucza i zakres muszą być wszystkie poniżej określonej długości znaków. Użyj string.len(), aby sprawdzić ich długość.

Dane (wartość klucza) są również przechowywane jako ciąg, niezależnie od ich początkowego typu. Możesz sprawdzić rozmiar danych za pomocą funkcji JSONEncode(), która konwertuje dane Luau na zserializowaną tabelę JSON.

Limity metadanych

Limity dotyczące liczby znaków w zdefiniowanej przez użytkownika metadanych.

Limity przepustowości

Limity przepustowości na poziomie klucza zapewniają, że wydajność jest optymalna na serwerach Roblox. Każdy limit dotyczy każdego pojedynczego klucza we wszystkich serwerach w doświadczeniu i odnawia się w czasie.

Roblox bada wykorzystanie kwoty związanej z kluczem w ciągu ostatnich 60 sekund. Jeśli wykorzystanie, w tym bieżące żądanie, mieści się w limicie przepustowości, żądanie jest zatwierdzane. Jeśli wykorzystanie przekracza limit, żądanie jest odrzucane.

Oprócz powyższych limitów przepustowości, Roblox organizuje dane w partycjach na podstawie wewnętrznego schematu. W rezultacie, gdy serwer zaplecza otrzymuje dużą liczbę żądań do tego samego magazynu danych, może to prowadzić do dalszego ograniczania. Niezależnie od przyczyny, ograniczenie objawia się jako błędy DatastoreThrottled lub KeyThrottled, w zależności od tego, czy limit przepustowości został przekroczony dla pojedynczego magazynu danych, czy klucza. Te komunikaty o błędach dotyczą zarówno uporządkowanych, jak i standardowych magazynów danych.

Limity przechowywania

Aby utrzymać stabilność i skalowalność przechowywania, magazyny danych używają limitu na poziomie gry dla twojego wykorzystania przechowywania.

Limit ten składa się z podstawowej alokacji dla każdej gry oraz dodatkowej alokacji w oparciu o liczbę użytkowników w całym okresie. Użytkownik w całym okresie to każdy użytkownik, który dołączył do twojej gry przynajmniej raz.

Limit przechowywania oblicza się za pomocą następującego wzoru Całkowity limit przechowywania najnowszej wersji = 500 MB + 1 MB × liczba użytkowników w całym okresie.

Wykorzystanie przechowywania mierzy się za pomocą skompresowanego rozmiaru najnowszej wersji każdego klucza. Magazyny danych automatycznie kompresują twoje dane przed przechowaniem, więc unikaj wstępnej kompresji. Wstępna kompresja dodaje niepotrzebne obciążenie CPU i może zmniejszyć skuteczność wbudowanej kompresji magazynów danych. Przechowując nieskompresowane dane, automatycznie korzystasz z ulepszeń algorytmów kompresji Robloxa i przyszłych optymalizacji opartych na schematach.

Tylko najnowsza wersja każdego klucza liczy się do twojego wykorzystania przechowywania. Usunięte klucze i zastąpione wersje, chociaż nadal dostępne przez API wersji w czasie ich okresu przechowywania, nie liczą się do twojego wykorzystania przechowywania. Jednak magazyny danych usunięte za pomocą metody Open Cloud DeleteDataStore nadal liczą się do wykorzystania przechowywania w czasie ich 30-dniowego okresu przetwarzania usunięcia, aż do ich trwałego usunięcia.