معلمات استعلام واجهة برمجة التطبيقات هي أزواج ذات قيمة أساسية يتم إلحاقها بعنوان URL لطلب واجهة برمجة التطبيقات لإرسال معلومات إضافية إلى الخادم. أنها تسمح للعملاء (مثل متصفحات الويب أو التطبيقات) بتحديد معايير معينة أو تمرير البيانات عند تقديم طلب إلى الخادم.

تتم إضافة معلمات الاستعلام إلى نهاية عنوان URL بعد علامة الاستفهام (؟). كل معلمة عبارة عن زوج من المفاتيح والقيمة، مع الفصل بين المفتاح والقيمة بعلامة التساوي (=). إذا كانت هناك معلمات استعلام متعددة، فسيتم فصلها بعلامة العطف (&).

كيفية استخدام معلمات الاستعلام:
تصفية البيانات: يمكن للعملاء استخدام معلمات الاستعلام لتصفية البيانات التي يريدونها. على سبيل المثال، قد يطلب ?category=books من الخادم إرجاع العناصر من فئة "الكتب" فقط.

ترقيم الصفحات: تُستخدم معلمات الاستعلام غالبًا لترقيم الصفحات في طلبات واجهة برمجة التطبيقات، مما يسمح للعميل بتحديد صفحة النتائج التي سيتم جلبها وعدد العناصر في كل صفحة. مثال: ?page=2&limit=10.

الفرز والترتيب: يمكن استخدام معلمات الاستعلام لتحديد كيفية فرز البيانات. على سبيل المثال، يمكن لـ ?sort=price&order=asc توجيه الخادم لإرجاع العناصر مرتبة حسب السعر بترتيب تصاعدي.

تمرير مصطلحات البحث: غالبًا ما تستخدم واجهات برمجة التطبيقات (API) معلمات الاستعلام للسماح للعملاء بالبحث عن البيانات. على سبيل المثال، يمكن استخدام ?search=laptop للعثور على جميع المنتجات التي تطابق المصطلح "كمبيوتر محمول".

تتميز معلمات الاستعلام بمرونة عالية ويمكن استخدامها بطرق مختلفة، اعتمادًا على كيفية تصميم واجهة برمجة التطبيقات. فهي تسمح بالتفاعل الديناميكي بين العميل والخادم، مما يسهل طلب البيانات المخصصة.

1. التعامل الأساسي مع معلمات الاستعلام يوضح معالج API هذا كيفية استخراج معلمات الاستعلام واستخدامها لإرجاع تحية مخصصة.

// pages/api/greet.js

export default function handler(req, res) {
  const { name } = req.query; // Get the 'name' query parameter
  const greeting = name ? `Hello, ${name}!` : 'Hello, stranger!';

  res.status(200).json({ message: greeting });
}

مثال للاستخدام:
/api/greet?name=John سيعود { "message": "مرحبًا جون!"
/api/greet سيعود { "message": "مرحبًا أيها الغريب!"

1. معلمات الاستعلام المتعددة في هذا المثال، يقوم معالج API باستخراج معلمات استعلام متعددة لإرجاع استجابة منسقة بناءً على مدخلات المستخدم.

// pages/api/user.js

export default function handler(req, res) {
  const { name, age } = req.query; // Get 'name' and 'age' query parameters

  if (!name || !age) {
    res.status(400).json({ error: 'Name and age are required' });
    return;
  }

  res.status(200).json({ message: `User ${name} is ${age} years old.` });
}

مثال للاستخدام:
/api/user?name=Jane&age=28 سيُرجع { "message": "عمر المستخدم Jane 28 عامًا."
/api/user?name=Jane سيُرجع { "خطأ": "الاسم والعمر مطلوبان"

1. معلمات الاستعلام الاختيارية ذات القيم الافتراضية يوضح هذا المثال كيفية التعامل مع معلمات الاستعلام الاختيارية من خلال توفير القيم الافتراضية عندما تكون المعلمات مفقودة.

// pages/api/score.js

export default function handler(req, res) {
  const { player = 'Anonymous', score = '0' } = req.query; // Default values if missing

  res.status(200).json({ message: `${player} scored ${score} points!` });
}

مثال للاستخدام:
/api/score?player=Alex&score=100 سيرجع { "message": "سجل Alex 100 نقطة!"
سيعود /api/score { "message": "سجل المجهول 0 نقطة!"

1. التعامل مع المصفوفات في معلمات الاستعلام يسمح Next.js بتمرير معلمات الاستعلام كمصفوفات. يوضح هذا المثال كيفية التعامل مع مجموعة من القيم.

// pages/api/tags.js

export default function handler(req, res) {
  const { tags } = req.query; // Get 'tags' query parameter (array)

  if (!tags) {
    res.status(400).json({ error: 'Tags are required' });
    return;
  }

  res.status(200).json({ message: `You have selected these tags: ${tags.join(', ')}` });
}

مثال للاستخدام:
/api/tags?tags=javascript&tags=react سيُرجع { "message": "لقد حددت هذه العلامات: javascript، رد فعل"
/api/tags سيرجع { "خطأ": "العلامات مطلوبة"

1. ترقيم الصفحات مع معلمات الاستعلام يوضح هذا المعالج كيفية تنفيذ ترقيم الصفحات باستخدام معلمات الاستعلام للصفحة والحد.

// pages/api/items.js

export default function handler(req, res) {
  const { page = 1, limit = 10 } = req.query; // Default values for page and limit
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex   Number(limit);

  // Dummy data for demonstration
  const items = Array.from({ length: 100 }, (_, i) => `Item ${i   1}`);
  const paginatedItems = items.slice(startIndex, endIndex);

  res.status(200).json({
    currentPage: page,
    perPage: limit,
    items: paginatedItems,
  });
}

مثال للاستخدام:
/api/items?page=2&limit=5 سيعيد العناصر الخمسة التالية، مثل { "items": ["Item 6"، "Item 7"، "Item 8"، "Item 9"، "Item 10"]
/api/items (القيم الافتراضية) ستُرجع أول 10 عناصر، مثل { "items": ["Item 1"، "Item 2"، ...، "Item 10"]

توضح هذه الأمثلة مرونة استخدام معلمات الاستعلام في مسارات واجهة برمجة تطبيقات Next.js، والتي تغطي الأنماط الشائعة مثل المعلمات الفردية أو المتعددة، والقيم الاختيارية، والمصفوفات، وترقيم الصفحات.