درس مصغّر · العربية

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

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

ابدأ الدرس التفاعلياقرأ ملاحظات الدرس

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

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

قبل أن تبدأ

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

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

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

ما الذي ستتعلمه؟

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

ملفات ورشة العمل

الخطوة 1

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

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

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

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

مثال عملي

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

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

GitHub: جلب مستودع

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

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

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

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

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

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

مثال محلول

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

GitHub: جلب مستودع

Extra implementation exercise

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

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

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

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

الخطوة 2

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

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

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

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

مثال عملي

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

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

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

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

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

اقرأ 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;

Extra implementation exercise

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

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

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

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

الخطوة 3

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

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

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

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

مثال عملي

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

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

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

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

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

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

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

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

مثال محلول

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

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

Extra implementation exercise

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

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

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

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

الخطوة 4

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

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

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

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

مثال عملي

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

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

Start hereملفات ورشة العمل

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

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

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

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

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

مثال محلول

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

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

Extra implementation exercise

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

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

أضف 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 ووضع عدم الاتصال. امحُ البطاقة السابقة في بداية البحث التالي؛ يجب ألا يحتفظ الخطأ بأعداد قديمة أو يستبدل البيانات غير المتاحة بصفر.

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

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

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

واصل التعلّم

استكشف الدروس الأخرى