الرموز الحدودية وأخطاء تخزين البيانات

يمكن أن تفشل الطلبات التي تقوم بها إلى تخزين البيانات بسبب اتصال ضعيف أو مشاكل أخرى. لمعالجة الأخطاء وإرجاع رسائل مع رمز خطأ، قم بلف وظائف تخزين البيانات في pcall().

تعني مكالمة الكتابة الفاشلة، مثل UpdateAsync(), أن خادم اللعبة لم يتلق استجابة ناجحة. لا يضمن دائمًا أن الكتابة في الخلفية لم تحدث. في بعض سيناريوهات الفشل، قد تكون حالة الكتابة النهائية غير معروفة للمتصل حتى يتم التحقق منها بقراءة لاحقة بدون ذاكرة تخزين مؤقت.

مرجع رموز الخطأ

رموز أخطاء الخادم

الحدود

تمتلك نماذج البيانات حدودًا. إذا تجاوزت تجربة هذه الحدود، تقوم الخدمة تلقائيًا بتقييد استخدام تخزين البيانات للتجربة وتسبب وضع الطلبات المستقبلية في واحدة من قوائم الانتظار التالية:

• تعيين
• تعيين مرتب
• الحصول
• الحصول المرتب

تتم معالجة الطلبات في قائمة الانتظار بالترتيب الذي تم استلامها فيه. تستمر الوظيفة المستدعاة في التخلي عن الطلب طالما أن طلبها لا يزال في قائمة الانتظار. إذا كان مفتاح تخزين البيانات نفسه مقيدًا، يتم وضع الطلب في قائمة الانتظار ولكن يتم تخطيه مؤقتًا.

تحتوي كل قائمة انتظار على حد 30 طلبًا. عند الوصول إلى حد قائمة الانتظار، تفشل الطلبات مع رمز خطأ في نطاق 301-306، مما يدل على أنه تم إسقاط الطلبات بالكامل.

حدود الوصول

تخزين البيانات خاضع لكل من حدود التجربة والحدود على مستوى الخادم.scale حدود مستوى التجربة تتوسع مع إجمالي المستخدمين المتزامنين عبر التجربة، بينما تم تكوين حدود مستوى الخادم لتستخدم كأداة من قبل المنشئ.

حدود التجربة

يسمح لكل تجربة بعدد معين من طلبات تخزين البيانات بناءً على نوع تخزين البيانات، ونوع الطلب، وعدد المستخدمين المتزامنين. بالنسبة لكل نوع من أنواع تخزين البيانات ونوع الطلب، يتم مشاركة الحد بين جميع الوظائف المذكورة.

• تستهلك UpdateAsync() من كل من ميزانية طلب القراءة والكتابة. ستقوم مكالمة واحدة بتقليل كلا الحدين.
• يشارك خادم اللعبة و Open Cloud ميزانية; يمكن أن يتم تقييد حركة مرور Open Cloud بواسطة الاستخدام داخل التجربة (وعكس ذلك). انظر Control rate limits للحصول على إرشادات إضافية.

تخزين البيانات القياسية

تخزين البيانات المرتبة

التحكم في حدود المعدل

نظرًا لأن طلبات السحابة المفتوحة وخادم اللعبة مشتركة، من المهم التحكم بشكل مستقل في مقدار ما يمكن أن يستهلكه كل منهما من الميزانية.

خادم اللعبة

تتضمن الخوادم حدودًا مدمجة، كما هو موصوف أعلاه. استخدم مجموعة من SetRateLimitForRequestType() و GetRequestBudgetForRequestType() للحفاظ على التحكم الدقيق في مساهمة الخوادم الفردية في الميزانية الإجمالية.

السحابة المفتوحة

تتطلب طلبات السحابة المفتوحة حل تحديد معدلات خارجي. نوصي بإحدى النهجين التاليين:

• (بسيط) إضافة مهلة قصيرة بعد كل طلب، خاصة إذا كنت تستدعي نفس API في حلقة مستمرة. قم بتعيين هذه المهلة إلى 60 / (استھلاك الميزانية المطلوب في الدقيقة) ثوانٍ، كحد أعلى. لاحظ أن هذا الأسلوب لا يسمح بإرسال الطلبات دفعة واحدة.
• (موثوق) تنفيذ محدد معدل محلي باستخدام استراتيجية دلو متسرب.

تشمل أمثلة التعليمات البرمجية Node.js التالية تنفيذات مرجعية.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('The API_KEY environment variable is not set.');
}

const apiHeaderKey = 'x-api-key';

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

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

// --- إعداد قيود معدل لكل عملية (طلبات في الدقيقة) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// الحد الأعلى لكل عملية: 60 / (طلبات في الدقيقة) ثوانٍ.
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));

// ينفذ الطلب، ثم ينتظر مدة هذه العملية قبل الإرجاع.
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) // يجب أن يكون الجسم سلسلة
    }, 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(`\nProcessing entry: ${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(`Response: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('An error occurred during execution:', error);
    }
})();

حدود الخادم

تحتوي كل خادمة على حد معدل قابل للتكوين لكل نوع طلب، بناءً على عدد اللاعبين في تلك الخادمة. تحصل الخوادم على دفعة إضافية لمرة واحدة من ميزانية الطلبات الإضافية عندما يتم إنشاؤها لأول مرة. استخدم GetRequestBudgetForRequestType() لتأكيد عدد طلبات تخزين البيانات التي يمكن للخادم الحالي إجراؤها في أي وقت.

هذه الحدود قابلة للتكوين من قبل المنشئ باستخدام SetRateLimitForRequestType() API. باستخدام واجهة البرمجة هذه، يمكن للمنشئ تكوين حدود معدلات تخزين البيانات الخاصة بهم لكل نوع طلب.

تطبق حدود معدل الحدود الافتراضية التالية إذا لم يتم استدعاء واجهة البرمجة:

تخزين البيانات القياسية

تخزين البيانات المرتبة

حدود البيانات

يحدد تخزين البيانات مقدار البيانات التي يمكن استخدامها لكل إدخال.

يجب أن يكون اسم تخزين البيانات، اسم المفتاح، و النطاق جميعها تحت طول معين من الحروف. استخدم string.len() للتحقق من طولها.

تُخزن البيانات (قيمة المفتاح) أيضًا كسلسلة، بغض النظر عن نوعها الأولي. يمكنك التحقق من حجم البيانات باستخدام دالة JSONEncode(), التي تحول بيانات Luau إلى جدول JSON متسلسل.

حدود البيانات الوصفية

حدود عدد الحروف في البيانات الوصفية التي يحددها المستخدم.

حدود الإنتاج

تحدد حدود الإنتاج لكل مفتاح الأداء الأمثل على خوادم Roblox. تنطبق كل حدود على كل مفتاح على حدة عبر جميع الخوادم في تجربة وتنتعش بشكل دوري.

تقوم Roblox بفحص استخدام الحصة المرتبطة بالمفتاح خلال الستين ثانية الماضية. إذا كان الاستخدام، بما في ذلك الطلب الحالي، ضمن حد الإنتاج، يتم الموافقة على الطلب. إذا تجاوز الاستخدام الحد، يتم رفض الطلب.

بالإضافة إلى حدود الإنتاج المذكورة أعلاه، تنظم Roblox البيانات في أجزاء بناءً على مخطط داخلي. نتيجة لذلك، عندما يستقبل الخادم الخلفي حجمًا كبيرًا من الطلبات إلى نفس تخزين البيانات، قد يؤدي ذلك إلى مزيد من التقييد. بصرف النظر عن السبب، يظهر التقييد إما كأخطاء DatastoreThrottled أو KeyThrottled، اعتمادًا على ما إذا كان قد تم تجاوز حد الإنتاج لتخزين بيانات واحد أو مفتاح. تنطبق رسائل الخطأ هذه على كل من تخزين البيانات المرتبة والقياسية.

حدود التخزين

للحفاظ على استقرار التخزين وقابليته للتوسع، تستخدم مخازن البيانات حدًا على مستوى اللعبة لاستخدامك للتخزين.

يتكون هذا الحد من تخصيص أساسي لكل لعبة بالإضافة إلى تخصيص إضافي استنادًا إلى عدد المستخدمين مدى الحياة. المستخدم مدى الحياة هو أي مستخدم انضم إلى لعبتك مرة واحدة على الأقل.

يتم حساب حد التخزين باستخدام الصيغة التالية Total latest version storage limit = 500 MB + 1 MB × lifetime user count.

يتم قياس استخدام التخزين باستخدام الحجم المضغوط لأحدث إصدار من كل مفتاح. تقوم مخازن البيانات تلقائيًا بضغط بياناتك قبل التخزين، لذا تجنب ضغطها مسبقًا بنفسك. قد يضيف الضغط المسبق عبئًا غير ضروري على وحدة المعالجة المركزية وقد يقلل من فعالية ضغط مخازن البيانات المدمج. من خلال تخزين البيانات غير المضغوطة، يمكنك الاستفادة تلقائيًا من التحسينات في خوارزميات ضغط روبلوكس والتحديثات المستقبلية القائمة على المخططات.

فقط أحدث إصدار من كل مفتاح يُحسب تجاه استخدام التخزين الخاص بك. المفاتيح المحذوفة والإصدارات المتقادمة، رغم أنها لا تزال قابلة للوصول من خلال واجهات برمجة التطبيقات للإصدارات خلال فترة الاحتفاظ بها، لا تحسب تجاه استخدام تخزينك. ومع ذلك، فإن مخازن البيانات المحذوفة عبر أسلوب Open Cloud DeleteDataStore تظل تعتبر ضمن استخدام التخزين خلال فترة معالجة الحذف البالغة 30 يومًا، حتى يتم حذفها نهائيًا.