الاستبدال باستخدام PUT
جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 3 من 20.
يستبدل PUT عنصرًا. يمثّل محتوى الطلب الحالة الجديدة الكاملة للعنصر، ويُرسل إلى عنوان URL الخاص بالعنصر، وأي حقل لا يتضمنه محتوى الطلب يأخذ قيمته الافتراضية. يؤدي إرسال طلب PUT نفسه مرتين إلى النتيجة نفسها، لذا فإن PUT متكرر الأثر: يمكن للعميل إعادة إرساله بعد انتهاء المهلة. أما POST فليس كذلك، لأن إرسال POST مرة ثانية يضيف عنصرًا ثانيًا.
app.MapPut("/api/products/{id:int}", (int id, ProductInput input) =>
{
var index = products.FindIndex(p => p.Id == id);
if (index == -1) return Results.NotFound();
products[index] = new Product(id, input.Name, input.Price);
return Results.Ok(products[index]);
});يأتي المعرّف من المسار، وليس من محتوى الطلب أبدًا، لذا لا يستطيع العميل نقل منتج إلى معرّف آخر. تُرجع FindIndex موضع العنصر في القائمة، أو -1 عندما لا يوجد تطابق، ويخزّن products[index] = ... الإصدار الجديد في موضعه.
التحدي
سهلدع العملاء يستبدلون مهمة.
- في
Program.cs، اربطPUT /api/tasks/{id:int}بمعاملَيint idوTaskInput input. يكون شكل الجسم مماثلًا لجسم طلب POST. - اعثر على موضع المهمة باستخدام
tasks.FindIndex. عندما تكون النتيجة -1، أجب بـResults.NotFound()ولا تضف شيئًا. - وإلا، فخزّن
new TaskItem(id, input.Title, input.Done)في ذلك الموضع، وأجب عنه باستخدامResults.Ok. يجيبPUT /api/tasks/1مع{ "title": "Write the final brief", "done": true }بالرمز 200، ويعيد:{ "id": 1, "title": "Write the final brief", "done": true }
جرّب ذلك: اضغط على تشغيل، واختر PUT، واكتب المسار /api/tasks/1 والجسم أعلاه، ثم اضغط على إرسال: ستحصل على 200 والمهمة أعلاه. أرسل GET /api/tasks/1: سيظهر العنوان الجديد. أرسل PUT إلى /api/tasks/2 مع { "title": "Book the big room" }: كانت المهمة 2 منجزة، لكن الجسم لم يتضمن done، لذا ستعود "done": false. سيجيب طلب PUT إلى /api/tasks/99 بالرمز 404.
جرّب بنفسك
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var tasks = new List<TaskItem>
{
new(1, "Write the project brief", false),
new(2, "Book the meeting room", true),
new(3, "Send the invoice", false),
};
var nextId = 4;
app.MapGet("/api/tasks", () => tasks);
app.MapGet("/api/tasks/{id:int}", (int id) =>
{
var task = tasks.Find(t => t.Id == id);
return task is null ? Results.NotFound() : Results.Ok(task);
});
app.MapPost("/api/tasks", (TaskInput input) =>
{
var task = new TaskItem(nextId++, input.Title, input.Done);
tasks.Add(task);
return Results.Created($"/api/tasks/{task.Id}", task);
});
app.Run();
record TaskItem(int Id, string Title, bool Done);
record TaskInput(string Title, bool Done);
جميع دروس واجهات API بنمط REST
1الموارد والأفعال
الموارد وURLsالإنشاء باستخدام POST