Codici di errore e limiti del data store

Le richieste che effettui ai data store possono fallire a causa di una scarsa connettività o altri problemi. Per gestire gli errori e restituire messaggi con un codice di errore, avvolgi le funzioni del data store in pcall().

Una chiamata di scrittura fallita, come UpdateAsync(), significa che il server di gioco non ha ricevuto una risposta positiva. Ciò non garantisce sempre che la scrittura nel backend non sia avvenuta. In alcuni scenari di errore, lo stato finale della scrittura può essere sconosciuto al chiamante finché non viene verificato con una lettura successiva senza cache.

Riferimento dei codici di errore

Codici di errore del server

Limiti

I modelli di dati hanno limiti. Se un'esperienza supera questi limiti, il servizio limita automaticamente l'uso del data store dell'esperienza e fa sì che le richieste future vengano inserite in una delle seguenti code:

• Imposta
• Imposta ordinata
• Ottieni
• Ottieni ordinato

Le richieste in una coda vengono gestite nell'ordine in cui vengono ricevute. La funzione chiamata continua a sospendersi finché la sua richiesta è ancora in coda. Se la chiave del data store stessa è limitata, la richiesta viene inserita in una coda ma viene temporaneamente saltata.

Ogni coda ha un limite di 30 richieste. Quando il limite di una coda viene raggiunto, le richieste falliscono con un codice di errore nell'intervallo 301-306, indicando che le richieste sono state completamente scartate.

Limiti di accesso

I data store sono soggetti sia a limiti a livello di esperienza che del server. I limiti a livello di esperienza si adattano al numero totale di utenti simultanei nell'esperienza, mentre i limiti a livello di server sono configurabili e devono essere utilizzati come uno strumento dal creatore.

Limiti dell'esperienza

Ogni esperienza è autorizzata a un certo numero di richieste del data store in base al tipo di data store, tipo di richiesta e numero di utenti simultanei. Per ciascun tipo di data store e tipo di richiesta, il limite è condiviso tra tutte le funzioni elencate.

• UpdateAsync() consuma sia dal budget delle richieste di lettura che da quello delle scritture. Una singola chiamata decreta entrambi i limiti.
• Il server di gioco e Open Cloud condividono un budget; il traffico di Open Cloud può essere limitato dall'uso interno all'esperienza (e viceversa). Vedi Controllo dei limiti di velocità per ulteriori indicazioni.

Data store standard

Data store ordinati

Controllo dei limiti di velocità

Poiché le richieste di Open Cloud e del server di gioco sono condivise, è importante controllare in modo indipendente quanto ciascuna può consumare dal budget.

Server di gioco

I singoli server hanno limiti incorporati, come descritto sopra. Usa una combinazione di SetRateLimitForRequestType() e GetRequestBudgetForRequestType() per mantenere un controllo dettagliato sul contributo dei singoli server al budget totale.

Open Cloud

Le richieste di Open Cloud richiedono una soluzione esterna di limitazione della velocità. Raccomandiamo uno dei seguenti approcci:

• (Semplice) Aggiungi un breve timeout dopo ogni richiesta, specialmente se chiami la stessa API in un ciclo continuo. Imposta questo timeout uguale a 60 / (consumo desiderato del budget per minuto) secondi, come limite massimo. Nota che questo approccio non consente di inviare richieste in esplosioni.
• (Robusto) Implementa un limitatore di velocità locale utilizzando la strategia del bucket a perdita.

I seguenti campioni di codice Node.js includono implementazioni di riferimento.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('La variabile ambiente API_KEY non è impostata.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Configurazione della limitazione della velocità per operazione (richieste al minuto) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Limite superiore per il tempo per operazione: 60 / (richieste al minuto) secondi.
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));

// Effettua la richiesta, quindi attende l'intervallo di questa operazione prima di restituire.
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) // Il corpo deve essere una stringa
    }, 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(`\nElaborazione voce: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Stato: ${updateResponse.status}`);
            console.log(`Risposta: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Si è verificato un errore durante l\'esecuzione:', error);
    }
})();

Limiti del server

Ogni server ha un limite di velocità configurabile per ciascun tipo di richiesta, basato sul numero di giocatori in quel server. I server ricevono un'esplosione di richiesta di budget aggiuntiva una tantum quando vengono creati per la prima volta. Usa GetRequestBudgetForRequestType() per confermare il numero di richieste del data store che il server corrente può effettuare in qualsiasi momento.

Questi limiti sono configurabili dal creatore utilizzando l'API SetRateLimitForRequestType(). Usando questa API, un creatore può configurare i propri limiti di velocità per i data store per ciascun tipo di richiesta.

I seguenti limiti di velocità predefiniti si applicano se l'API non viene chiamata:

Data store standard

Data store ordinati

Limiti dei dati

I data store limitano la quantità di dati che possono essere utilizzati per voce.

Il nome del data store, il nome della chiave e l'ambito devono tutti essere sotto una certa lunghezza di caratteri. Usa string.len() per controllare la loro lunghezza.

I dati (valore della chiave) sono anche memorizzati come stringa, indipendentemente dal loro tipo iniziale. Puoi controllare la dimensione dei dati con la funzione JSONEncode(), che converte i dati Luau in una tabella JSON serializzata.

Limiti dei metadati

Limiti al numero di caratteri nei metadati definiti dall'utente.

Limiti di throughput

I limiti di throughput per chiave garantiscono che le prestazioni siano ottimali sui server Roblox. Ogni limite si applica a ciascuna chiave su tutti i server in un'esperienza e si aggiorna nel tempo.

Roblox esamina l'uso delle quote associate alla chiave negli ultimi 60 secondi. Se l'uso, inclusa la richiesta attuale, è all'interno del limite di throughput, la richiesta viene approvata. Se l'uso supera il limite, la richiesta viene negata.

Oltre ai limiti di throughput sopra indicati, Roblox organizza i dati in partizioni in base a uno schema interno. Di conseguenza, quando il server backend riceve un alto volume di richieste allo stesso data store, possono verificarsi ulteriori limitazioni. Indipendentemente dalla causa, il throttling si manifesta come errori DatastoreThrottled o KeyThrottled, a seconda che il limite di throughput sia stato superato per un singolo data store o una chiave. Questi messaggi di errore si applicano sia ai data store ordinati che standard.

Limiti di archiviazione

Per mantenere stabile e scalabile l'archiviazione, i data store utilizzano un limite a livello di gioco sul tuo utilizzo di archiviazione.

Questo limite consiste in un'allocazione di base per ciascun gioco più un'allocazione aggiuntiva basata sul numero di utenti in vita. Un utente in vita è qualsiasi utente che ha partecipato al tuo gioco almeno una volta.

Il limite di archiviazione viene calcolato utilizzando la seguente formula Limite totale di archiviazione dell'ultima versione = 500 MB + 1 MB × numero di utenti in vita.

L'utilizzo di archiviazione viene misurato utilizzando la dimensione compressa dell'ultima versione di ciascuna chiave. I data store comprimono automaticamente i tuoi dati prima dell'archiviazione, quindi evita di pre-comprimerli tu stesso. La pre-compressione aggiunge un sovraccarico CPU non necessario e può ridurre l'efficacia della compressione integrata dei data store. Memorizzando dati non compressi, benefici automaticamente dei miglioramenti agli algoritmi di compressione di Roblox e delle ottimizzazioni basate su schemi future.

Solo l'ultima versione di ciascuna chiave conta verso il tuo utilizzo di archiviazione. Le chiavi eliminate e le versioni superate, pur essendo ancora accessibili tramite le API delle versioni durante il loro periodo di conservazione, non contano verso il tuo utilizzo di archiviazione. Tuttavia, i data store eliminati tramite il metodo Open Cloud DeleteDataStore continuano a contare verso l'utilizzo di archiviazione durante il loro periodo di elaborazione di eliminazione di 30 giorni, fino a quando non vengono rimossi definitivamente.