إنتقل إلى المحتوى الرئيسي

Request():setParameter()

تضيف معاملاً لمتن الطلب (يُستخدم مع طلبات POST/PUT/PATCH). تتيح لك هذه الدالة إضافة بيانات سيتم إرسالها في متن الطلب.

التوقيع​

setParameter(key: string, value: string): Request

المعاملات​

المعاملاتالنوعالوصف
keystringاسم المعامل
valuestringقيمة المعامل

القيمة المعادة

Request - يُعيد كائن Request لاستخدامه في تسلسل الدوال (method chaining)

الوصف​

تضيف الدالة setParameter() زوجًا من المفتاح والقيمة إلى متن الطلب. تُستخدم هذه الدالة بشكل أساسي مع طلبات POST و PUT و PATCH عندما تحتاج إلى إرسال بيانات إلى الخادم. يمكنك استدعاء هذه الدالة عدة مرات لإضافة معاملات متعددة إلى متن الطلب.

أمثلة​

طلب POST أساسي مع المعاملات​

-- Send form data with POST request
local response = Request("https://api.example.com/users")
    :setParameter("name", "John Doe")
    :setParameter("email", "john@example.com")
    :setParameter("age", "30")
    :post()

طلب POST مع نوع محتوى JSON​

-- Send JSON data with POST request
local response = Request("https://api.example.com/posts")
    :setHeader("Content-Type", "application/json")
    :setParameter("title", "My New Post")
    :setParameter("body", "This is the content of my post")
    :setParameter("userId", "1")
    :post()

طلب PUT مع المعاملات​

-- Update a resource with PUT request
local response = Request("https://api.example.com/users/123")
    :setHeader("Content-Type", "application/json")
    :setParameter("name", "Jane Smith")
    :setParameter("email", "jane@example.com")
    :setParameter("status", "active")
    :put()

طلب PATCH لتحديثات جزئية​

-- Partially update a resource with PATCH
local response = Request("https://api.example.com/users/456")
    :setHeader("Content-Type", "application/json")
    :setParameter("email", "newemail@example.com")
    :setParameter("lastUpdated", "2023-12-01")
    :patch()

إرسال نموذج​

-- Submit a login form
local response = Request("https://example.com/login")
    :setHeader("Content-Type", "application/x-www-form-urlencoded")
    :setParameter("username", "myusername")
    :setParameter("password", "mypassword")
    :setParameter("remember", "true")
    :post()

استعلام بحث عبر POST​

-- Send search parameters via POST
local response = Request("https://api.example.com/search")
    :setParameter("query", "lua programming")
    :setParameter("limit", "10")
    :setParameter("sort", "relevance")
    :setParameter("filters", "books,tutorials")
    :post()

local results = response:getData()
local status = response:getResponseCode()

if status == 200 then
    print("Search results: " .. results)
else
    print("Search failed with status: " .. status)
end

بنية بيانات معقّدة​

-- Create a complex object with multiple nested parameters
local response = Request("https://api.example.com/orders")
    :setHeader("Content-Type", "application/json")
    :setParameter("customerId", "12345")
    :setParameter("productId", "67890")
    :setParameter("quantity", "2")
    :setParameter("shippingAddress", "123 Main St, City, State")
    :setParameter("paymentMethod", "credit_card")
    :post()

أنواع المعاملات​

عند استخدام setParameter()، تُعامَل جميع القيم كسلاسل نصية. إليك حالات الاستخدام الشائعة:

نوع المعاملمثالملاحظات
نصsetParameter("name", "John Doe")سلاسل نصية عادية
أرقامsetParameter("age", "30")يجب تمرير الأرقام كسلاسل نصية
تواريخsetParameter("date", "2023-12-01")استخدم صيغة ISO للتواريخ
قيم منطقيةsetParameter("active", "true")مرّر "true" أو "false" كسلاسل نصية
JSONsetParameter("data", '{"key":"value"}')يمكن تمرير سلاسل JSON كمعاملات

ملاحظات​

  • تُستخدم هذه الدالة بشكل أساسي مع طلبات POST و PUT و PATCH
  • تُعامَل جميع قيم المعاملات كسلاسل نصية
  • تُعيد الدالة كائن Request، مما يسمح بتسلسل الدوال (method chaining)
  • تُنسَّق المعاملات عادةً وفقًا لترويسة Content-Type
  • بالنسبة لطلبات GET، يجب تضمين المعاملات في سلسلة استعلام URL بدلاً من ذلك
  • تعتمد الصيغة الفعلية لمتن الطلب على ترويسة Content-Type المضبوطة عبر setHeader()
  • الاستدعاءات المتعددة لـ setParameter() بنفس المفتاح ستستبدل القيم السابقة