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

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

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

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

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

الحدود

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

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

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

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

حدود الوصول

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

حدود التجربة

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

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

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

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

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

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

خادم اللعبة

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

Open Cloud

تتطلب طلبات Open Cloud حلاً خارجيًا لتحديد معدل الطلبات. نوصي بإحدى الطرق التالية:

• (بسيطة) أضف مهلة قصيرة بعد كل طلب، خاصة إذا كنت تستدعي نفس واجهة برمجة التطبيقات في حلقة مستمرة. قم بتعيين هذه المهلة لتكون مساوية لـ 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() واجهة برمجة التطبيقات. باستخدام هذه الواجهة، يمكن للمنشئ تكوين حدود معدل تخزين البيانات الخاصة بهم لكل نوع طلب.

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

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

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

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

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

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

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

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

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

حدود الإنتاجية

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

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

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

حدود التخزين

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

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

يتم حساب حد التخزين باستخدام الصيغة التالية إجمالي حد التخزين لأحدث إصدار = 500 ميغابايت + 1 ميغابايت × عدد المستخدمين مدى الحياة.

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

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