طلبات HTTP داخل اللعبة

*This content is translated using AI (Beta) and may contain errors. To view this page in English, click here.

يمكنك استخدام HttpService لإرسال طلبات HTTP العامة إلى خدمات الويب الخارجية لحالات الاستخدام مثل التحليلات، تخزين البيانات، أو تسجيل الأخطاء. يدعم HttpService أيضًا نقاط نهاية معينة في Open Cloud.

تمكين طلبات HTTP

لا يتم تمكين طرق HttpService:GetAsync() و Class.HttpService:PostAsync() و Class.HttpService:RequestAsync() بشكل افتراضي. لإرسال الطلبات، يجب عليك السماح بطلبات HTTP تحت إعدادات التجربة للعبتك.

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

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

الاستخدام مع Open Cloud

يمكن لـ HttpService حاليًا استدعاء مجموعة فرعية من نقاط نهاية Open Cloud. يمكنك استدعاء هذه النقاط بنفس الطريقة التي ستستدعي بها أي نقطة نهاية أخرى عبر HttpService. الاختلاف الوحيد هو أنك يجب أن تتضمن مفتاح API لـ Open Cloud في الطلب:

توضح عينة الكود التالية كيفية تحديث عضوية مجموعة مستخدم من داخل لعبة:


local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- عند إرسال JSON، قم بتعيين هذا!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- محدد في Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("كانت الاستجابة ناجحة:", response.StatusCode, response.StatusMessage)
	else
		print("أرجعت الاستجابة خطأ:", response.StatusCode, response.StatusMessage)
	end
	print("نص الاستجابة:\n", response.Body)
	print("رؤوس الاستجابة:\n", HttpService:JSONEncode(response.Headers))
end

-- قم بتغليف الدالة في pcall() للسلامة
local success, errorMessage = pcall(request)
if not success then
	print("فشل إرسال طلب HTTP:", errorMessage)
end

نقاط نهاية Open Cloud المدعومة

النقاط التالية مدعومة. نظرًا للقيود الحالية على HttpService، لا يُسمح بسلسلة .. في معلمات مسار URL إلى المجالات الخاصة بـ Roblox. وهذا يعني، على سبيل المثال، أن محلات البيانات والمداخل التي تحتوي على هذه السلسلة غير متاحة حاليًا من HttpService.

الأصول

الحظر والحواجز

الإعدادات

متجر المبدعين

المنتجات المطورة

تمريرات اللعبة

متاجر البيانات والذاكرة

متاجر البيانات:

متاجر الذاكرة:

متاجر البيانات المرتبة:

المجموعات

المخزون

ListInventoryItems

تنفيذ Luau

الإشعارات

CreateUserNotification

الأماكن

العوالم

المستخدمون

القيود

يُسمح فقط برؤوس x-api-key و content-type.
يجب أن يكون رأس x-api-key من نوع Secret. راجع مخازن الأسرار.
لا يُسمح بسلسلة ".." في معلمات مسار URL.
يتم دعم بروتوكول HTTPS فقط.
لا يمكنك استخدام المنفذ 1194 أو أي منفذ أدنى من 1024، باستثناء 80 و 443. إذا حاولت استخدام منفذ محظور، ستحصل على إما خطأ 403 Forbidden أو ERR_ACCESS_DENIED.

حدود المعدل

لكل خادم لعبة روبلوكس، هناك حد قدره 2500 طلب Open Cloud في الدقيقة. يمكن أن يتسبب تجاوز ذلك في توقف طرق إرسال الطلبات لمدة حوالي 30 ثانية. قد تفشل أيضًا pcall() مع رسالة تفيد بأنه تم تجاوز عدد طلبات Open Cloud للحد المحدد.

طلبات Open Cloud لا تستهلك نفس الحد الإجمالي البالغ 500 طلب HTTP في الدقيقة المفروض على جميع الطلبات الأخرى.
لكل نقطة نهاية حدها الخاص لكل مالك مفتاح API (يمكن أن يكون مستخدمًا أو مجموعة) يتم تطبيقه بغض النظر عن مصدر الاستدعاءات (من HttpService أو الويب أو غيرها).

للحصول على معلومات تفصيلية حول حدود سرعة Open Cloud وقيود السرعة المعتمدة على المصادقة وأفضل الممارسات، راجع حدود المعدل.

أفضل الممارسات

لتحسين استخدامك لـ HttpService وتجنب تجاوز الحدود، طبق الممارسات التالية:

تعامل مع الأخطاء بسلاسة. يمكن أن تفشل طلبات الويب لأسباب عديدة. استخدم pcall() ولديك خطة للتواصل عندما تفشل الطلبات. علاوة على ذلك، تحقق بدقة من جميع البيانات المستلمة من واجهات برمجة التطبيقات الخارجية وقم بتطهيرها، لضمان صحة البيانات حيث يمكنك.
استخدم العودة الأسية للبقاء ضمن الحدود.

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

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

في بعض الحالات قد تضطر إلى استخدام HttpService:RequestAsync() لتضمين البيانات في جسم الطلب.
استخدم نقاط نهاية HTTP/2. يوفر HTTP/2 فوائد أداء كبيرة من خلال ميزات مثل ضغط الرؤوس ودمج الطلبات/الردود عبر اتصال واحد. تستخدم HttpService HTTP/2 تلقائيًا عند توفره. لاحظ أن مواصفة HTTP/2 تتطلب إرسال جميع أسماء الرؤوس لاحظ بشكل حرفي.

القابلية للملاحظة

يوفر لوحة القابلية للملاحظة رؤى وتحليلات لمراقبة واستكشاف استخدامك لـ HttpService. تتضمن لوحة المعلومات رسمين بيانيين أساسيين: عدد الطلبات الذي يتتبع حجم طلبات HttpService من لعبتك، و وقت الاستجابة الذي يقيس زمن الانتظار لنقاط النهاية للاستجابة.

الدوافع المتاحة للتصفية والتحليل تُعرّف على النحو التالي:

نوع الطلب

GET
POST
PUT
PATCH
DELETE
أخرى (لأنواع الطلبات غير المحددة)

الحالة

نجاح (رموز الحالة HTTP 1xx و 2xx)
إعادة توجيه (رموز الحالة HTTP 3xx)
400 (طلب خاطئ)
401 (غير مصرح)
403 (محظور)
404 (غير موجود)
429 (عدد كبير جدًا من الطلبات)
500 (خطأ في الخادم الداخلي)
503 (الخدمة غير متاحة)
ExternalError (أي رموز خطأ أخرى غير محددة عادت من الخدمة الخارجية)
InternalError (مشكلة عادت من HttpService داخل روبلوكس)

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

اعتبارات إضافية

يجب أن توفر الطلبات شكلًا آمنًا من المصادقة، مثل مفتاح سري مسبق المشاركة، حتى لا يتمكن الأشرار من التظاهر بأنهم أحد خوادمك في روبلوكس.
كن على علم بالقدرة العامة وسياسات تحديد المعدل لخوادم الويب التي تُرسل الطلبات إليها.

العربية