Codes d'erreur et limites de la base de données

Les requêtes que vous faites aux bases de données peuvent échouer en raison d'une mauvaise connectivité ou d'autres problèmes. Pour gérer les erreurs et renvoyer des messages avec un code d'erreur, enveloppez les fonctions de la base de données dans pcall().

Un appel d'écriture échoué, tel que UpdateAsync(), signifie que le serveur de jeu n'a pas reçu de réponse réussie. Cela ne garantit pas toujours que l'écriture en arrière-plan n'a pas eu lieu. Dans certains scénarios d'échec, l'état d'écriture final peut être inconnu pour l'appelant jusqu'à ce qu'il soit vérifié avec une lecture de suivi sans cache.

Référence des codes d'erreur

Codes d'erreur du serveur

Limites

Les modèles de données ont des limites. Si une expérience dépasse ces limites, le service limite automatiquement l'utilisation de la base de données de l'expérience et place les requêtes futures dans l'une des files d'attente suivantes :

• Définir
• Définir ordonné
• Obtenir
• Obtenir ordonné

Les requêtes dans une file d'attente sont traitées dans l'ordre où elles sont reçues. La fonction appelée continue de s'engager tant que sa requête est toujours dans la file d'attente. Si la clé de la base de données elle-même est limitée, la requête est placée dans une file d'attente mais est temporairement sautée.

Chaque file d'attente a une limite de 30 requêtes. Lorsque la limite d'une file d'attente est atteinte, les requêtes échouent avec un code d'erreur dans la plage 301-306, indiquant que les requêtes ont été totalement abandonnées.

Limites d'accès

Les bases de données sont soumises à la fois à des limites de niveau d'expérience et de serveur. Les limites de niveau d'expérience augmentent avec le nombre total d'utilisateurs simultanés à travers l'expérience, tandis que les limites de niveau de serveur sont configurables et destinées à être utilisées comme un outil par le créateur.

Limites de l'expérience

Chaque expérience est autorisée à un certain nombre de requêtes de base de données en fonction du type de base de données, du type de requête et du nombre d'utilisateurs simultanés. Pour chaque type de base de données et type de requête, la limite est partagée parmi toutes les fonctions répertoriées.

• UpdateAsync() consomme à la fois le budget des requêtes de lecture et d'écriture. Un seul appel diminuera les deux limites.
• Le serveur de jeu et le Cloud Ouvert partagent un budget ; Le trafic du Cloud Ouvert peut être limité par l'utilisation en expérience (et vice versa). Voir Contrôler les limites de taux pour des orientations supplémentaires.

Base de données standard

Base de données ordonnée

Contrôler les limites de taux

Étant donné que les demandes du Cloud Ouvert et du serveur de jeu sont partagées, il est important de contrôler de manière indépendante combien chacun peut consommer du budget.

Serveur de jeu

Les serveurs individuels ont des limites intégrées, comme décrit ci-dessus. Utilisez une combinaison de SetRateLimitForRequestType() et GetRequestBudgetForRequestType() pour maintenir un contrôle fin sur la contribution des serveurs individuels au budget total.

Cloud Ouvert

Les demandes du Cloud Ouvert nécessitent une solution externe de limitation de taux. Nous recommandons l'une des approches suivantes :

• (Simple) Ajoutez un court délai après chaque demande, surtout si vous appelez la même API dans une boucle continue. Fixez ce délai égal à 60 / (consommation budgétaire souhaitée par minute) secondes, comme limite supérieure. Notez que cette approche n'autorise pas les demandes à être envoyées par rafales.
• (Robuste) Implémentez un limiteur de taux local utilisant la stratégie du seau percé.

Les échantillons de code Node.js suivants incluent des implémentations de référence.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('La variable d\'environnement API_KEY n\'est pas définie.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- Configuration de limitation de taux par opération (requêtes par minute) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Espacement maximal par opération : 60 / (requêtes par min) secondes.
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));

// Exécute la requête, puis attend l'intervalle de cette opération avant de retourner.
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) // Le corps doit être une chaîne
    }, 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(`\nTraitement de l'entrée : ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Statut : ${updateResponse.status}`);
            console.log(`Réponse : ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Une erreur est survenue durant l\'exécution :', error);
    }
})();

Limites du serveur

Chaque serveur a une limite de taux configurable pour chaque type de requête, basée sur le nombre de joueurs dans ce serveur. Les serveurs reçoivent une rafale de budget de requêtes supplémentaires une seule fois lorsqu'ils sont créés. Utilisez GetRequestBudgetForRequestType() pour confirmer le nombre de requêtes de la base de données que le serveur actuel peut effectuer à tout moment.

Ces limites sont configurables par le créateur à l'aide de l SetRateLimitForRequestType() API. En utilisant cette API, un créateur peut configurer ses propres limites de taux pour les bases de données pour chaque type de requête.

Les limites de taux par défaut suivantes s'appliquent si l'API n'est pas appelée :

Base de données standard

Base de données ordonnée

Limites de données

Les bases de données limitent la quantité de données pouvant être utilisée par entrée.

Le nom de la base de données, le nom de la clé et le scope doivent tous être sous une certaine longueur de caractères. Utilisez string.len() pour vérifier leur longueur.

Les données (valeur de clé) sont également stockées sous forme de chaîne, indépendamment de leur type initial. Vous pouvez vérifier la taille des données avec la fonction JSONEncode(), qui convertit les données Luau en une table JSON sérialisée.

Limites de métadonnées

Limites au nombre de caractères dans les métadonnées définies par l'utilisateur.

Limites de débit

Les limites de débit par clé garantissent que les performances sont optimales sur les serveurs Roblox. Chaque limite s'applique à chaque clé individuelle sur tous les serveurs dans une expérience et se rafraîchit avec le temps.

Roblox examine l'utilisation du quota associé à la clé au cours des 60 dernières secondes. Si l'utilisation, y compris la requête actuelle, est dans la limite de débit, la requête est approuvée. Si l'utilisation dépasse la limite, la requête est refusée.

En plus des limites de débit ci-dessus, Roblox organise les données en partitions en fonction d'un schéma interne. Par conséquent, lorsque le serveur en arrière-plan reçoit un volume élevé de requêtes pour la même base de données, cela peut entraîner un ralentissement supplémentaire. Quelle que soit la cause, le ralentissement se manifeste par des erreurs DatastoreThrottled ou KeyThrottled, selon que la limite de débit a été dépassée pour une seule base de données ou une clé. Ces messages d'erreur s'appliquent à la fois aux bases de données ordonnées et standard.

Limites de stockage

Pour maintenir un stockage stable et évolutif, les bases de données utilisent une limite de niveau de jeu sur votre utilisation de stockage.

Cette limite consiste en une allocation de base pour chaque jeu plus une allocation supplémentaire basée sur le nombre d'utilisateurs en lifetime. Un utilisateur en lifetime est tout utilisateur qui a rejoint votre jeu au moins une fois.

La limite de stockage est calculée à l'aide de la formule suivante Limite de stockage de la dernière version totale = 500 Mo + 1 Mo × compte des utilisateurs en lifetime.

L'utilisation du stockage est mesurée en utilisant la taille compressée de la dernière version de chaque clé. Les bases de données compressent automatiquement vos données avant le stockage, donc évitez de les compresser vous-même. La pré-compression ajoute une surcharge CPU inutile et peut réduire l'efficacité de la compression intégrée des bases de données. En stockant des données non compressées, vous profitez automatiquement des améliorations apportées aux algorithmes de compression de Roblox et des optimisations basées sur le schéma à venir.

Seule la dernière version de chaque clé compte pour votre utilisation de stockage. Les clés supprimées et les versions remplacées, tout en étant toujours accessibles via les API de version pendant leur période de conservation, ne comptent pas pour votre utilisation de stockage. Cependant, les bases de données supprimées via la méthode du Cloud Ouvert DeleteDataStore continuent de compter pour l'utilisation de stockage pendant leur période de traitement de suppression de 30 jours, jusqu'à ce qu'elles soient définitivement supprimées.