Request():put()

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

التوقيع

put(): Response

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

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

الوصف

ترسل الدالة put() طلب HTTP PUT إلى العنوان المحدّد عند إنشاء كائن Request. تُستخدم طلبات PUT عادةً لاستبدال موارد موجودة بالكامل ببيانات جديدة، أو لإنشاء مورد على عنوان محدد.

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

أمثلة

طلب PUT أساسي

-- Replace a user's complete data
local response = Request("https://api.example.com/users/123")
    :setParameter("name", "John Smith")
    :setParameter("email", "john.smith@example.com")
    :setParameter("age", "35")
    :setParameter("status", "active")
    :put()

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

-- Replace an entire post with new content
local response = Request("https://api.example.com/posts/456")
    :setHeader("Content-Type", "application/json")
    :setHeader("Authorization", "Bearer your-token-here")
    :setParameter("title", "Completely New Title")
    :setParameter("body", "Completely new post content")
    :setParameter("userId", "1")
    :setParameter("status", "published")
    :put()

معالجة استجابة PUT

-- 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("name", "Jane Doe")
    :setParameter("email", "jane.doe@example.com")
    :setParameter("bio", "Software Developer")
    :setParameter("website", "https://jane.example.com")
    :setParameter("location", "San Francisco")
    :put()

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

if statusCode == 200 then
    print("User updated successfully!")
    print("Updated user data: " .. data)
elseif statusCode == 201 then
    print("User created successfully!")
    print("New user data: " .. data)
else
    print("Failed to update user. Status: " .. statusCode)
end

PUT لإنشاء مورد

-- Create a new resource at a specific URL
local response = Request("https://api.example.com/files/document-v2")
    :setHeader("Content-Type", "application/json")
    :setParameter("content", "This is the new document content")
    :setParameter("version", "2.0")
    :setParameter("author", "John Doe")
    :put()

local status = response:getResponseCode()
if status == 201 then
    print("Document created successfully!")
elseif status == 200 then
    print("Document replaced successfully!")
else
    print("Operation failed with status: " .. status)
end

تحديث PUT مشروط

-- 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("title", "Updated Article Title")
    :setParameter("content", "Updated article content")
    :setParameter("author", "John Doe")
    :put()

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

استبدال مورد بالكامل

-- Replace an entire product with new data
local response = Request("https://api.example.com/products/456")
    :setHeader("Content-Type", "application/json")
    :setParameter("name", "Premium Widget")
    :setParameter("description", "A high-quality widget with advanced features")
    :setParameter("price", "99.99")
    :setParameter("stock", "50")
    :setParameter("category", "electronics")
    :setParameter("specs", '{"color": "black", "weight": "200g", "warranty": "2 years"}')
    :put()

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

ملاحظات

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