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

Request():patch()

ينفّذ طلب PATCH ويُعيد كائن Response. تُستخدم هذه الدالة لتحديث جزئي لمورد على الخادم.

التوقيع​

patch(): Response

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

Response - كائن الاستجابة الذي يحتوي على رد الخادم

الوصف​

ترسل الدالة patch() طلب HTTP PATCH إلى العنوان المحدّد عند إنشاء كائن Request. تُستخدم طلبات PATCH عادةً لإجراء تحديثات جزئية على الموارد الموجودة، بتعديل الحقول المُمرَّرة فقط في متن الطلب.

استخدم setParameter() لإضافة بيانات إلى متن الطلب قبل استدعاء patch().

أمثلة​

طلب PATCH أساسي​

-- Update only the email field of a user
local response = Request("https://api.example.com/users/123")
    :setParameter("email", "newemail@example.com")
    :patch()

طلب PATCH مع ترويسات JSON​

-- Partially update a post with multiple fields
local response = Request("https://api.example.com/posts/456")
    :setHeader("Content-Type", "application/json")
    :setHeader("Authorization", "Bearer your-token-here")
    :setParameter("title", "Updated Post Title")
    :setParameter("status", "published")
    :patch()

معالجة استجابة PATCH​

-- Update user profile and handle response
local response = Request("https://api.example.com/users/789")
    :setHeader("Content-Type", "application/json")
    :setHeader("Authorization", "Bearer token123")
    :setParameter("bio", "Updated bio information")
    :setParameter("website", "https://mywebsite.com")
    :patch()

local data = response:getData()
local statusCode = response:getResponseCode()

if statusCode == 200 then
    print("User updated successfully!")
    print("Updated data: " .. data)
elseif statusCode == 204 then
    print("User updated successfully! (No content returned)")
else
    print("Failed to update user. Status: " .. statusCode)
end

تحديث PATCH مشروط​

-- Update only if resource hasn't been modified
local response = Request("https://api.example.com/articles/123")
    :setHeader("Content-Type", "application/json")
    :setHeader("If-Match", "etag-value-here")
    :setHeader("Authorization", "Bearer token")
    :setParameter("content", "Updated article content")
    :setParameter("lastModified", "2023-12-01")
    :patch()

local status = response:getResponseCode()
if status == 412 then
    print("Update failed: Resource has been modified by another user")
elseif status == 200 or status == 204 then
    print("Article updated successfully")
end

PATCH مع تحديد الحقول​

-- Update specific fields while leaving others unchanged
local response = Request("https://api.example.com/products/456")
    :setHeader("Content-Type", "application/json")
    :setParameter("price", "29.99")
    :setParameter("stock", "150")
    :setParameter("discount", "10")
    :patch()

local updatedProduct = response:getData()
print("Product updated: " .. updatedProduct)

ملاحظات​

  • استخدم setParameter() لإضافة بيانات إلى متن الطلب قبل استدعاء patch()
  • يجب أن تحتوي طلبات PATCH على الحقول التي تريد تحديثها فقط، وليس المورد بالكامل
  • يختلف PATCH عن PUT في أن PATCH يجري تحديثات جزئية، بينما PUT يستبدل المورد بالكامل
  • عمليات PATCH الناجحة تُعيد عادةً:
    • 200 OK مع المورد المحدَّث في متن الاستجابة
    • 204 No Content إذا نجح التحديث دون الحاجة إلى متن استجابة
  • تُعيد الدالة كائن Response يمكنك استخدامه للوصول إلى بيانات الاستجابة ورمز الحالة
  • تحقّق دائمًا من رمز حالة الاستجابة للتأكد من نجاح الطلب
  • طلبات PATCH ليست بالضرورة تكرارية (idempotent) — فقد يكون لإرسال نفس الطلب عدة مرات آثار مختلفة بحسب التنفيذ