Codes d'erreur et limites des magasins de données

Les requêtes que vous effectuez vers les magasins 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 magasin 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 final de l'écriture 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 du magasin de données de l'expérience et place les futures requêtes 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 dans lequel elles sont reçues. La fonction appelée continue de céder tant que sa requête est toujours en file d'attente. Si la clé du magasin de données elle-même est limitée, la requête est placée dans une file d'attente mais est temporairement ignoré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é complètement abandonnées.

Limites d'accès

Les magasins de données sont soumis à la fois à des limites d'expérience et de serveur. Les limites de niveau d'expérience évoluent avec le nombre total d'utilisateurs simultanés dans 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 d'expérience

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

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

Magasins de données standard

Magasins de données ordonnés

Contrôler les limites de taux

Parce que les requêtes Open Cloud et serveur de jeu sont partagées, il est important de contrôler indépendamment combien chacune 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 précis sur la contribution des serveurs individuels au budget total.

Open Cloud

Les requêtes Open Cloud nécessitent une solution de limitation de taux externe. Nous recommandons l'une des approches suivantes :

• (Simple) Ajoutez un court délai après chaque requête, surtout si vous appelez la même API dans une boucle continue. Définissez ce délai égal à 60 / (consommation de budget souhaitée par minute) secondes, comme une limite supérieure. Notez que cette approche ne permet pas d'envoyer des requêtes en rafales.
• (Robuste) Implémentez un limiteur de taux local en utilisant la stratégie du seau qui fuit.

Les exemples 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));

// Effectue 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 s\'est produite pendant 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émentaire lors de leur première création. Utilisez GetRequestBudgetForRequestType() pour confirmer le nombre de requêtes de magasin de données que le serveur actuel peut effectuer à tout moment.

Ces limites sont configurables par le créateur en utilisant l'API SetRateLimitForRequestType(). En utilisant cette API, un créateur peut configurer ses propres limites de taux de magasins 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 :

Magasins de données standard

Magasins de données ordonnés

Limites de données

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

Le nom du magasin 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, quel que soit 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é unique sur tous les serveurs d'une expérience et se rafraîchit au fil du 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 basées sur un schéma interne. En conséquence, lorsque le serveur arrière reçoit un volume élevé de requêtes vers le même magasin de données, cela peut entraîner un throttling supplémentaire. Quelle qu'en soit la cause, le throttling se manifeste par des erreurs DatastoreThrottled ou KeyThrottled, selon que la limite de débit a été dépassée pour un magasin de données unique ou une clé. Ces messages d'erreur s'appliquent à la fois aux magasins de données ordonnés et standard.

Limites de stockage

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

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

La limite de stockage est calculée en utilisant la formule suivante Limite de stockage de la dernière version totale = 500 Mo + 1 Mo × nombre d'utilisateurs à vie.

L'utilisation du stockage est mesurée en utilisant la taille compressée de la dernière version de chaque clé. Les magasins 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 magasins de données. En stockant des données non compressées, vous bénéficiez automatiquement des améliorations des 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, bien qu'encore accessibles via les API de version pendant leur période de conservation, ne comptent pas pour votre utilisation de stockage. Cependant, les magasins de données supprimés via la méthode Open Cloud DeleteDataStore continuent de compter pour l'utilisation de stockage pendant leur période de traitement de suppression de 30 jours, jusqu'à ce qu'ils soient définitivement supprimés.