الدروسكيف تعرض بيانات من واجهة API خارجية على موقعك

درس مصغّر 16 من 30 · ربط البيانات والذكاء الاصطناعي

افتح البحث الجاهز

لمن هذا الدرس؟

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

اطلب قيمة من الخدمة بدل كتابة رقم ثابت في الصفحة.

هدف هذا الدرس

  • ابحث عن مستودع عام حقيقي.
  • اعرض نتيجة إضافية مفيدة بمساعدة مساعد برمجة.
  • ميّز غياب مستودع مطابق من عدم توفر الخدمة.
شرح ومثال محلول وتدريب

قبل أن تبدأ

تحتاج إلى الحزمة المرفقة واتصال بالإنترنت ومعاينة HTTP محلية يستطيع مساعد البرمجة تشغيلها. يقرأ هذا المثال مستودعات GitHub العامة دون رمز وصول خاص؛ وتظل قيود المعدل وتوفر الخدمة سارية.

تحقّق من مهارات البداية

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

  1. كيف تنشئ أول موقع شخصي لك

    أنشئ تعريفًا بنفسك وقسمًا للمشاريع وطريقة للتواصل انطلاقًا من ملفات البداية المرفقة.

الوقت المتوقع: 14–26 دقيقة

تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. تتشاطر طلبات GitHub غير المصادَق عليها حصة استخدام تستند إلى عنوان IP؛ وقد تبلغها الاختبارات المتكررة.

افهم الفكرة

اطلب من المساعد تشغيل مجلد public المرفق عبر HTTP. استخدم مثال octocat / Hello-World في نسخة البداية وفعّل زر البحث.

قارن هوية المستودع والعدد المُعادين بنتيجة الخدمة في ذلك الوقت. لا تثبت رقمًا قديمًا في الكود وتعرضه كأنه حديث.

مثال عملي

عدد نجوم محفوظ في نص الصفحة لا يتغير عندما يتغير المستودع.

شغّل صفحة البحث عن المستودعات العامة المرفقة عبر HTTP محلي. حافظ على عرض النص الآمن الموجود، ولا تضف رمز وصول خاصًا إلى ملفات المتصفح. ساعدني في اختبار مستودع حقيقي وآخر غير موجود وطلب خدمة فاشل. ثم أضف عدد العناصر المفتوحة الموثق وساعدني في مقارنته باستجابة API. تولَّ تعديلات الكود نيابة عني.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

جرّب بنفسك

أي مستودع بحثت عنه؟ وما النتيجة التي عرضتها الصفحة التي تعمل فعلًا؟

عرض حل نموذجي مشروح

مثال سجل بحث بعدد مختلق: «عند اختباري، طلبت octocat / Hello-World. أعادت الصفحة octocat/Hello-World و12 نجمة؛ وطابقت الهوية والعدد المعروضان الاستجابة التي فحصتها». العدد 12 افتراضي لتوضيح المثال، وليس معلومة حالية عن ذلك المستودع.

تتغير أعداد النجوم. يحتاج سجلك إلى العدد ووقت الاختبار اللذين لاحظتهما فعلًا؛ وإذا لم ترد الخدمة، فسجل تلك الحالة بدل وضع عدد المثال مكانها.

ما تتضمنه الإجابة السليمة

  • يسمي مالك المستودع العام والمستودع المطلوب فعلًا والهوية المسترجعة.
  • يذكر العدد والوقت الملحوظين أو فشل الخدمة المحدد، دون تثبيت قيمة المثال في الكود.
كيف يعمل؟ (اختياري)

اعرض بيانات من خدمة أخرى

حمّل اسم مستودع عام ووصفه وعدد نجومه من GitHub.

واجهة API طريقة محددة تطلب بها البرمجيات بيانات أو إجراءً. هنا يطلب موقعك مستودعًا واحدًا من GitHub ويتلقى JSON بدل صفحة HTML.

نستخدم عملية قراءة عامة لتتعلم معالجة الطلبات دون البدء بالمصادقة. يمكن أن تتغير النتيجة بين الطلبات؛ فهي ملاحظة حالية وليست رقمًا تثبته في الشيفرة.

مثال محلول

للمالك octocat والمستودع Hello-World، يكون مسار الطلب /repos/octocat/Hello-World على api.github.com. تعرض الصفحة القيمتين المُرجعتين full_name وstargazers_count.

GitHub: جلب مستودع

تمرين تقني إضافي

ما الفرق بين نسخ عدد النجوم إلى HTML وجلبه عند الضغط على الزر؟

عرض حل نموذجي مشروح

يحتفظ HTML المنسوخ بالقيمة القديمة حتى تعديله. أما fetch فيطلب الاستجابة الحالية في تلك اللحظة، لكنه يحتاج إلى معالجة التحميل والفشل لأن الخدمة أو الشبكة قد لا تستجيب.

  • تشرح متى تُحصّل القيمة.
  • تدرك أن الطلب الخارجي قد يفشل.

الخطوة 1 · كيف تعرض بيانات من واجهة API خارجية على موقعك

افحص استجابة ناجحة واحدة

استخدم ملاحظة تستطيع مقارنتها بالمصدر.

شرح ومثال محلول وتدريب

افهم الفكرة

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

يجب ألا يُعامل طلب يعيد خطأً كنتيجة طبيعية. لا تحتاج إلى كتابة كود الطلب أو الخطأ لتقييم النتيجة الظاهرة.

مثال عملي

قيم استجابة توضيحية: ينبغي أن يظهر full_name = practice/example وstargazers_count = 12 على الصفحة باسم المستودع practice/example و12 نجمة. هذه قيم خيالية لفهم التحويل، وليست العدد الحالي لمثال GitHub المرفق.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

جرّب بنفسك

هل طابقت نتيجة الصفحة استجابة المستودع التي فحصتها؟

عرض حل نموذجي مشروح

مثال تحويل بقيم استجابة خيالية: ينبغي أن تعرض استجابة تحتوي على full_name = practice/example وstargazers_count = 12 الاسم practice/example و12 نجمة. ويجب ألا تحتفظ باسم المستودع السابق أو تحول العدد المفقود إلى صفر.

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

ما تتضمنه الإجابة السليمة

  • يطابق هوية الصفحة وعدد النجوم مع استجابة الخدمة العامة نفسها.
  • لا يعرض استجابة خطأ أو حقلًا مفقودًا بوصفه نتيجة طبيعية قيمتها صفر.
كيف يعمل؟ (اختياري)

أنشئ طلبًا واحدًا وافحصه

رمّز مدخل المستخدم وافحص الاستجابة قبل استخدامها.

اقرأ public/app.js وشغّل الصفحة المرفقة عبر HTTP. تُبقي encodeURIComponent كل قيمة للمالك أو المستودع ضمن مقطع المسار الخاص بها. المضيف ثابت؛ ولا يقدم الزائر نقطة نهاية اعتباطية.

تُحل fetch حتى مع أخطاء HTTP مثل 404، لذا لا يكفي انتظارها. افحص response.ok والحالات المعنية، وحلّل JSON، ثم تحقق من الحقول التي تحتاج إليها الميزة. تعرض textContent النصوص الخارجية بوصفها نصًا.

يوضح المقتطف القصير أدناه فحص HTTP العام. يعالج app.js الكامل أولًا 404 والاستجابات المقيّدة أو المحدودة المعدل معالجة محددة، ثم يفحص الحالات غير الناجحة الأخرى ويحلّل JSON ويتحقق من الحقول. حافظ على هذا الترتيب عند إضافة حقل معروض جديد.

مثال محلول

ينبغي أن يظل الوصف الذي يتضمن أقواسًا زاوية نصًا ظاهرًا، وألا يتحول إلى ترميز للصفحة. ينبغي أن يعرض 404 رسالة عن الفقد أو الوصول العام بدل بطاقة نجاح فارغة.

if (!response.ok) throw Error('Request failed');
const data = await response.json();
result.textContent = data.full_name;

تمرين تقني إضافي

لماذا لا يكتشف try/catch وحده كل استجابة HTTP غير ناجحة؟

عرض حل نموذجي مشروح

قد تنتج أخطاء HTTP كائن Response عاديًا. افحص status/ok، وألقِ خطأً أو عالجه قبل اعتبار المتن المستودع المطلوب.

  • تعرف أن fetch قد تُحل عند 404/500.
  • تفحص الحالة قبل عرض النجاح.

الخطوة 2 · كيف تعرض بيانات من واجهة API خارجية على موقعك

جرّب عدم العثور وعدم توفر الخدمة

اجعل حالات الفشل المختلفة مفهومة.

شرح ومثال محلول وتدريب

افهم الفكرة

جرّب اسم مستودع غير موجود. وبمساعدة المساعد، اختبر أيضًا طلبًا محظورًا أو فاشلًا في صفحة التدريب المحلية. أبقِ نص البحث المدخل متاحًا للتصحيح أو إعادة المحاولة.

ينبغي أن تميّز الصفحة مستودعًا غير موجود من فشل مؤقت في الخدمة. لا تضف رمزًا خاصًا إلى المتصفح لتجاوز حد المعدل.

مثال عملي

«لم يُعثر على المستودع» و«الخدمة غير متاحة؛ حاول مجددًا» توجّهان الزائر إلى إجراءين مختلفين.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

جرّب بنفسك

ماذا عرضت حالتا الفشل؟ وهل استطاع الزائر متابعة المحاولة؟

عرض حل نموذجي مشروح

مثال سجل فشل: «أظهر اسم مستودع مختلق Repository not found or not publicly accessible. وعند حجب الطلب عمدًا لاختبار فشل محلي، عرض البحث خطأ؛ وظلت حقول المالك والمستودع متاحة وأمكن تجربة الزر مجددًا».

الطلب المحجوب محاكاة، وليس دليلًا على انقطاع GitHub فعليًا. ينبغي أن يؤدي بلوغ حد الطلبات إلى المحاولة لاحقًا، لا وضع رمز حساب خاص في كود الصفحة العام.

ما تتضمنه الإجابة السليمة

  • يسجل نتيجتين مختلفتين لمستودع مفقود ولاختبار فشل طلب بمساعدة المساعد.
  • يتأكد من بقاء البحث قابلًا للتصحيح أو إعادة المحاولة دون إضافة رمز حساب خاص إلى المتصفح.
كيف يعمل؟ (اختياري)

اجعل حالات الفشل قابلة للتمييز

عدم وجود مستودع وانقطاع الشبكة ونفاد الحصة مشكلات مختلفة.

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

قد يرفض GitHub الطلبات غير المصادَق عليها بسبب حدود تستند إلى عنوان IP. لا تعالج ذلك بتضمين رمز خاص في المتصفح. للاستخدام المستمر المصادَق عليه، انقل استخدام بيانات الاعتماد إلى مسار خادم مضبوط، واستخدم التخزين المؤقت حيث يناسب.

مثال محلول

إذا بقيت بطاقة نجاح ظاهرة أسفل «Not found»، فقد يظن الزائر أن البيانات القديمة تخص البحث الجديد. محو النتيجة القديمة يجعل حالة الطلب الحالي واضحة.

GitHub: حدود معدل طلبات REST API

تمرين تقني إضافي

يفشل بحث بعد اختبارات كثيرة. هل ينبغي أن تخبر الواجهة المستخدم أن المستودع لديه صفر نجوم؟

عرض حل نموذجي مشروح

لا. الصفر قيمة بيانات حقيقية. أبلغ عن عدم توافر البيانات أو تقييدها وافحص الحالة؛ يظل العدد مجهولًا حتى توفره استجابة ناجحة.

  • لا تحوّل البيانات غير المتاحة إلى صفر.
  • تفحص حالة الطلب والأدلة المتعلقة بحصة الاستخدام.

الخطوة 3 · كيف تعرض بيانات من واجهة API خارجية على موقعك

أضف نتيجة مفيدة

صف المعلومة الجديدة ودع المساعد يربطها.

شرح ومثال محلول وتدريب

افهم الفكرة

اطلب من المساعد إضافة حقل الاستجابة open_issues_count بجوار النتيجة الحالية وتسميته «المشكلات وطلبات السحب المفتوحة». يشمل مجموع GitHub هذا الفئتين؛ ولا يجوز تسميته عدد الأخطاء فقط. افتح المرجع المرفق بعد تجربة نسختك.

قارن القيمة المعروضة بالاستجابة الفعلية، ثم أعد اختبارات النجاح والغياب وعدم التوفر. أنت تحكم على المعنى والحالات الملحوظة؛ والمساعد يتولى التنفيذ في المتصفح.

مثال عملي

قد تمثل قيمة افتراضية 5 للحقل open_issues_count مشكلتين مفتوحتين وثلاثة طلبات سحب مفتوحة. أما عنوان «5 أخطاء» فيدعي ما لا يثبته الحقل.

ملفات هذه الخطوة

ابدأ هناملفات ورشة العمل

افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.

جرّب بنفسك

أضف مجموع المشكلات وطلبات السحب المفتوحة. كيف قارنت القيمة المعروضة بالاستجابة، وماذا حدث في اختباري الغياب وعدم التوفر؟

ما المطلوب إنجازه: صفحة البحث المعدلة ونتائج الحالة الطبيعية وعدم العثور وفشل الخدمة التي لاحظتها.

عرض حل نموذجي مشروح

مثال تحويل: «عند استجابة خيالية تحتوي على open_issues_count = 5، تعرض الصفحة 5 مشكلات وطلبات سحب مفتوحة. قد يشمل ذلك مشكلتين وثلاثة طلبات سحب؛ وليس عدد خمسة أخطاء برمجية».

مثال سجل اختبار: «طابق البحث الطبيعي الاستجابة؛ واحتفظ المستودع الغائب برسالة عدم العثور؛ وأبقت محاكاة الطلب المحجوب خطأ يسمح بالمحاولة مجددًا». ينبغي أن يتضمن تسليمك القيمة الفعلية المطابقة، وأن يحدد أي اختبار لم تنفذه.

ما تتضمنه الإجابة السليمة

  • يعرض open_issues_count بوصفه مجموع المشكلات وطلبات السحب المفتوحة، لا الأخطاء أو المشكلات وحدها.
  • يقارن القيمة الجديدة باستجابة، ويكرر حالات النجاح والغياب وعدم التوفر.
كيف يعمل؟ (اختياري)

مهمتك: أضف حقل مستودع مفيدًا واحدًا

أضف عدد المشكلات مع الحفاظ على حدود واضحة بين البيانات والأخطاء.

اعرض open_issues_count بعد التحقق من أنه عدد منتهٍ. لاحظ أن عدد المستودع في GitHub يشمل طلبات السحب وفق الوثائق؛ لا تسمّه عددًا دقيقًا لتقارير الأعطال وحدها.

سجّل بحثًا ناجحًا ومستودعًا مفقودًا ومحاولة دون اتصال. ضمّن ما يراه الزائر أثناء الطلب وبعد كل نتيجة.

مثال محلول

تشرح تسمية مثل «Open issues and pull requests» («المشكلات وطلبات السحب المفتوحة») ما تقيسه القيمة بدقة أكبر من «Bugs» («الأعطال»).

يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.

تمرين تقني إضافي

وسّع النتيجة بالعدد الموثق للعناصر المفتوحة وأظهر الحالات الثلاث كلها.

عرض حل نموذجي مشروح

أضف open_issues_count إلى الحقول التي تتحقق منها بعد معالجة الحالة الناجحة. اشترط عددًا منتهيًا، ثم سمّه «Open issues and pull requests» لأن حقل مستودع GitHub هذا يشمل النوعين. يحافظ السكربت المرجعي الكامل على العرض باستخدام textContent وعلى حالات التحميل والخطأ القائمة.

بيانات اختبار توضيحية: full_name='sample/site', stargazers_count=3, open_issues_count=2 تنتج «sample/site — 3 stars — 2 open issues and pull requests»، أي 3 نجوم و2 من المشكلات وطلبات السحب المفتوحة. لا يدعي ذلك أن العنصرين كليهما عطلان.

أعد اختبار مستودع عام ناجح وحالة 404 ووضع عدم الاتصال. امحُ البطاقة السابقة في بداية البحث التالي؛ يجب ألا يحتفظ الخطأ بأعداد قديمة أو يستبدل البيانات غير المتاحة بصفر.

  • تتحقق من العدد المضاف وتسمّيه بدقة.
  • لا تبقى نتيجة نجاح قديمة بعد فشل بحث جديد.

هل أفادك هذا الدرس؟

اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.