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

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

تفعيل طلبات HTTP

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

الاستخدام في الإضافات

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

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

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

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

1. إنشاء مفتاح API لـ Open Cloud.
2. حفظ مفتاح API في مخزن الأسرار الخاص بك.
3. قم بإجراء الطلب.

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

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"), -- تم تعيينه في مركز المبدعين
		},
		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.

الأصول

• GetAsset
• ListAssetVersions
• GetAssetVersion

الحظر والحجب

• ListUserRestrictions (Place)
• GetUserRestriction (Place)
• UpdateUserRestriction (Place)
• ListUserRestrictions (Universe)
• GetUserRestriction (Universe)
• UpdateUserRestriction (Universe)
• ListUserRestrictionLogs (Universe)

التكوينات

• GetConfigRepositoryValues
• GetConfigRepositoryDraft
• UpdateDraft
• DeleteDraft
• OverwriteDraft
• GetConfigRepositoryFull
• PublishDraft
• ListRevisions
• RestoreRevision

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

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

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

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

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

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

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

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

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (With Scope)
• CreateDataStoreEntry (With Scope)
• GetDataStoreEntry (With Scope)
• DeleteDataStoreEntry (With Scope)
• UpdateDataStoreEntry (With Scope)
• IncrementDataStoreEntry (With Scope)
• ListDataStoreEntryRevisions (With Scope)

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

• CreateMemoryStoreQueueItem
• DiscardMemoryStoreQueueItems
• ReadMemoryStoreQueueItems
• ListMemoryStoreSortedMapItems
• CreateMemoryStoreSortedMapItem
• GetMemoryStoreSortedMapItem
• DeleteMemoryStoreSortedMapItem
• UpdateMemoryStoreSortedMapItem
• FlushMemoryStore

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

• ListOrderedDataStoreEntries
• CreateOrderedDataStoreEntry
• GetOrderedDataStoreEntry
• DeleteOrderedDataStoreEntry
• UpdateOrderedDataStoreEntry
• IncrementOrderedDataStoreEntry

المجموعات

• GetGroup
• ListGroupJoinRequests
• AcceptGroupJoinRequest
• DeclineGroupJoinRequest
• ListGroupMemberships
• UpdateGroupMembership
• ListGroupRoles
• GetGroupRole
• GetGroupShout

المخزونات

• ListInventoryItems

تنفيذ Luau

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (with version)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

الإشعارات

• CreateUserNotification

الأماكن

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

الأكوان

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

المستخدمون

• GetUser
• GenerateUserThumbnail

القيود

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

حدود المعدل

لكل خادم لعبة Roblox، هناك حد قدره 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 داخل Roblox)

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

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

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