أدلة عملية معمقة

استعلام API عام وحفظ استخراج قابل للتحقق

حدد الطلب والصفحات والأخطاء والاستجابة الأصلية قبل تحويل البيانات.

آخر تحديث :

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

رسم توضيحي مولّد بالذكاء الاصطناعي

كيف تعيد الاستخراج دون ادعاء شمول غير مثبت؟

تجيب API عن طلب بمخطط وفي لحظة محددة. لا يثبت ذلك طلب القاعدة كلها أو ثباتها بين الاستدعاءات. افصل سجل الجمع عن التحليل.

  1. اختيار الوصول

    اقرأ الوثائق الرسمية: النسخة والنطاق والشروط والمصادقة والحدود. ابحث عن تصدير رسمي للقاعدة الكاملة.

  2. طلب صغير

    احفظ نقطة الوصول والطريقة والمعلمات والفلاتر والترتيب. فضّل المعرّفات ولا تنشر مفاتيح أو رموزاً.

  3. فحص الاستجابة

    سجل حالة HTTP والوقت والصيغة والأخطاء. تحقق من الحقول والوحدات؛ قد تحتوي 200 على فراغ أو خطأ وظيفي.

  4. متابعة الصفحات

    راجع الإجمالي والصفحات والمؤشرات. عدّ الصفوف والمعرّفات الفريدة وسجل التكرار وشرط التوقف. قد تتغير القاعدة أثناء الجمع.

  5. حفظ الأصل

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

  6. معالجة التغير

    اتبع تعليمات إعادة المحاولة عند 429 أو تعذر الخدمة. الاستخراج الجديد ملاحظة جديدة؛ قارن المخطط والنطاق أيضاً.

أمثلة طلبات صغيرة

توضح العناوين الصياغة؛ تحقق من التوفر والمصادقة والشروط في الوثائق.

ورشة قراءة البيانات

سجل إعادة تحقق لا استخراج فارغ جديد

تبادلات HTTP في DEMO افتراضية. لا يتصل هذا القسم بخادم ولا يعيد طلباً.

بيانات وسجلات افتراضية للتعلم: لا تأتي هذه النتائج من استعلام مباشر لأي خدمة.

فصل النسخة والتحقق وحد الطلبات

يحفظ العميل تمثيلاً لـarea=A مع ETag. تحد السياسة الافتراضية المحاولات باثنتين ولا تضمن إتاحة الخدمة.

  1. حفظ النسخة الأولى

    التبادل الافتراضي
    GET area=A → 200 مع جسم وETag "demo-v1"
    الحالة المحفوظة
    جسم مرتبط بالطلب المطابق
    قرار السيناريو
    احفظ المرشحات والإصدار والتمثيل معاً.
  2. إعادة تحقق الاختيار نفسه

    التبادل الافتراضي
    الطلب نفسه مع If-None-Match → 304 دون جسم
    الحالة المحفوظة
    نسخة مطابقة متاحة
    قرار السيناريو
    أعد استخدامها ولا تسجل استخراجاً من صفر صفوف.
  3. تغيير الاختيار

    التبادل الافتراضي
    طلب جديد area=B
    الحالة المحفوظة
    لا توثق النسخة A المنطقة B
    قرار السيناريو
    عالجه منفصلاً ولو تشابه نص ETag.
  4. بلوغ حد

    التبادل الافتراضي
    429; Retry-After: 15
    الحالة المحفوظة
    فشلت المحاولة وليست نتيجة صفراً
    قرار السيناريو
    انتظر حسب الإشارة؛ بعد محاولتين توقف وسجل.

أي سجل يفصل حالات الجمع بصورة صحيحة؟

افتح كل اقتراح لمقارنة تشخيصه. قد تبقى فحوص إضافية ضرورية.

304: اختيار فارغ جديد

لا؛ يستخدم السيناريو نسخة الاختيار نفسه. غياب الجسم لا ينشئ جدولاً فارغاً.

نسخ بيانات A في استخراج B

لا؛ يغير ذلك نطاق المشاهدات بصمت. المعلمات جزء من السجل.

حفظ مرجع النسخة A وتسجيل التوقف بسبب الحد منفصلاً

نعم. يجب تحديد البيانات المستخدمة والمحاولات التي لم تقدم استخراجاً جديداً.

سجل عميل افتراضي

الاختيار: GET /demo?area=A
النسخة: جسم محفوظ؛ ETag="demo-v1"
الشرط: If-None-Match="demo-v1"
الاستجابة: 304؛ مرجع النسخة A
محاولة أخرى: 429؛ Retry-After=15 ثانية
سياسة DEMO: محاولتان كحد أقصى ثم التوقف
حقوق إعادة النشر: فحص منفصل

حد المحاولتين من المثال لا من RFC. دون نسخة صالحة لا تختلق محتوى؛ حضر جلباً جديداً وفق سياسة الخدمة.

توثيق القواعد منفصل عن الأمثلة الافتراضية

مقارنة حالات وتمارين أخرى

صفحة واحدة

راجع الإجمالي والمؤشر التالي قبل عرض تعداد شامل.

الغياب صار صفراً

ميّز null والحقل المفقود والقائمة الفارغة والصفر؛ يؤثر ذلك في المتوسط.

الطلب نفسه وأرقام جديدة

يوثق Eurostat قاعدة بأحدث النسخ. احفظ استخراجاً مؤرخاً لإعادة حساب قديم.

تمرين مع الحل

حالة 200 مع خطأ في التطبيق

مثال افتراضي: القيم والوثائق لتعلم الطريقة ولا تصف مؤسسة حقيقية.

يشترط عقد هذه API الافتراضية success=true قبل المعالجة. افحص استجابة HTTP وحالة التطبيق ووجود النتائج كلّاً على حدة.

إذا تجاوز الجدول الشاشة فمرره أفقياً؛ تعمل أسهم لوحة المفاتيح عند تركيز المنطقة.

المعطيات الأولية
العنصرالمعلومة المرصودة
حالة HTTP200
مؤشر التطبيقsuccess=false
الرسالة المستلمةالرسالة: بلوغ الحصة
مصفوفة النتائجلم تُقدم مصفوفة

ما ينبغي التحقق منه

  1. افحص حالة HTTP ومؤشر التطبيق منفصلين.
  2. تحقق من وجود البنية المطلوبة.
  3. احفظ الخطأ دون نشر عدد زائف.
قراءة الحل

الحل والقرار

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

إذا تغيرت الحالة

إذا احتوت استجابة ناجحة مصفوفة فارغة فعلاً، فقد يثبت الصفر للاستعلام والنطاق المحددين. أعد الاختبار مع success=true لكن بجسم JSON مبتور؛ فلا تكفي الحالة والعلامة بعد. ارفض الدفعة الناقصة واحفظ نقطة الاستئناف وتحقق من أن قيمة جزئية لم تستبدل آخر استخراج معتمد.

السجل الواجب حفظه

احفظ الاستعلام دون أسرار والحالة والخطأ والعقد وحالة الإعادة.

مرجع توثيقي : IETF — RFC 9110, 200 OK · تاريخ الاطلاع

مرجع موثق

Wikidata: تختار truthy رتبة لا حقيقة مصدقة

Truthy إسقاط تقني لكل كيان وخاصية: تستبعد العبارات المفضلة العادية عند وجودها، وإلا تختار العادية. ليست تصويتاً آلياً للمصادر أو اختياراً لأحدث تاريخ.

Wikidata: تختار truthy رتبة لا حقيقة مصدقة
المرجعالقيمة أو الصيغةما الذي يحدده
PreferredRankPreferredتختار جميع العبارات المفضلة للزوج. لا يضمن التفضيل قيمة وحيدة.
NormalRankNormalتختار العادية فقط عند غياب المفضلة للزوج. قد تكون قيم عادية متعددة مشروعة.
DeprecatedRankDeprecatedتستبعد العبارات ذات الرتبة المهملة من truthy، مع بقائها كاملة لتوثيق أخطاء أو قيم مرفوضة.
wdt:Best non-deprecated rankيستخدم المسار المباشر أفضل الرتب غير المهملة دون مؤهلات. لا يضمن الحداثة أو الاكتمال أو الإسناد.
wikibase:BestRankFull statement selectionيختار هذا النوع عقد العبارات الكاملة بأفضل رتبة مع إبقاء المؤهلات والمراجع متاحة.
ScopeEntity + propertyالقاعدة لكل كيان وخاصية. تفضيل السكان لا يختار تاريخ التأسيس أو الاسم.

ما يُحفظ في الملف

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

هل قيمة wdt: هي الأحدث بالضرورة؟

لا. الرتبة والتأهيل الزمني آليتان مختلفتان. افحص الزمن وسياسة الرتبة؛ قد تتعايش عبارات مفضلة متعددة.

الوثائق الأصلية

تاريخ الاطلاع على الوثائق .

مرجع موثق

واجهة البنك الدولي: التمييز بين ثلاثة تواريخ واستعادة الوحدة

تتضمن استجابة JSON أكثر من قيمة. يخص المقتطف الحقيقي كثافة فنلندا في 2023. يشير رأس الاستجابة إلى تحديث WDI في 8 أكتوبر 2026، واستُخرجت هذه اللقطة في 23 أكتوبر. تجيب التواريخ الثلاثة عن أسئلة مختلفة.

date2023lastupdated2026-10-08extracted2026-10-23
واجهة البنك الدولي: التمييز بين ثلاثة تواريخ واستعادة الوحدة
المرجعالقيمة أو الصيغةما الذي يحدده
date2023سنة الرصد. لا تصبح 2026 لمجرد تنفيذ الطلب في 2026.
lastupdated2026-10-08تاريخ التحديث في رأس المصدر. لا يثبت وحده مراجعة هذه القيمة المحددة.
extracted2026-10-23تاريخ إعداد اللقطة المحلية؛ لا يحل محل فترة الرصد أو تاريخ المصدر.
unit""حقل unit فارغ. لكن تعريف EN.POP.DNST يحدد أشخاصاً لكل كم² من اليابسة؛ الفراغ لا يعني أن القيمة بلا وحدة.
decimal / value0 / 18.3705454665088حقل decimal يساوي صفراً بينما تحتوي value على كسور عشرية. احتفظ بالقيمة الواردة ولا تفسر الحقل كهامش خطأ.
pages / total1 / 4تسع صفحة استجابة واحدة المشاهدات الأربع. قد يكون طلب آخر متعدد الصفحات؛ تحقق من pages وtotal قبل اعتبار الجمع مكتملاً.

الطلب الكامل · الكثافة

https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100

رأس الاستجابة ومشاهدة FIN المحفوظان

[
    {
        "page": 1,
        "pages": 1,
        "per_page": 100,
        "total": 4,
        "sourceid": "2",
        "lastupdated": "2026-10-08"
    },
    [
        {
            "indicator": {
                "id": "EN.POP.DNST",
                "value": "Population density (people per sq. km of land area)"
            },
            "country": {
                "id": "FI",
                "value": "Finland"
            },
            "countryiso3code": "FIN",
            "date": "2023",
            "value": 18.3705454665088,
            "unit": "",
            "obs_status": "",
            "decimal": 0
        }
    ]
]

ما يُحفظ في الملف

هذه لقطة مؤرخة من الواجهة، بلا تحديث آلي عند تحميل الصفحة. لا يثبت رمز الدولة المشترك تطابق النطاق الجغرافي لجميع السلاسل. لإعادة التحليل، احتفظ بالطلب الكامل والتعاريف والقيم المفقودة ولا تحول null إلى صفر.

الوثائق الأصلية

تاريخ الاطلاع على الوثائق .

مرجع موثق

معلمات النموذج: حفظ الفراغات وعلامات + والأسماء المتكررة

قائمة المعلمات تسلسل مرتب من أزواج الاسم والقيمة. قد يتكرر الاسم نفسه. تطبق الأداة application/x-www-form-urlencoded عبر URLSearchParams على قيمتين من سطر واحد ثم تعيد قراءة النتيجة، ولا ترسل نموذجاً.

tag → C++ & IAtag → ététag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9getAll("tag") → ["C++ & IA", "été"]
معلمات النموذج: حفظ الفراغات وعلامات + والأسماء المتكررة
المرجعالقيمة أو الصيغةما الذي يحدده
U+0020+يُسلسل الفراغ U+0020 إلى + في هذا التنسيق. ليست هذه قاعدة عامة لكل أجزاء عنوان URL.
+%2Bتتحول علامة + الأصلية في القيمة إلى %2B. يؤدي لصق C++ مباشرة في سلسلة مرمزة مسبقاً إلى قراءة علامتي + كفراغين.
&%26تتحول & داخل القيمة إلى %26 فلا تنشئ معلمة إضافية.
=%3Dتتحول = داخل القيمة إلى %3D، بينما تبقى علامة الفصل البنيوية بين الاسم والقيمة =.
été%C3%A9t%C3%A9تُرمز المحارف غير ASCII انطلاقاً من UTF-8. تمثل تسلسلات النسبة المئوية بايتات لا عدد الحروف الظاهرة.
append / get / getAll / setordered pairsتحتفظ append بظهور جديد. تعيد get القيمة الأولى وgetAll جميع القيم بالترتيب. تستبدل set الأولى وتحذف بقية مرات ظهور الاسم نفسه.

استكشاف معلمتين لهما الاسم نفسه

قيمتان توضيحيتان تحسبان في هذه الصفحة.

حُفظ الزوجان بترتيبهما.

التسلسل المرمز

tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9

القيم المعاد قراءتها عبر getAll

["C++ & IA","été"]

القيمة الأولى عبر get

"C++ & IA"

ما يُحفظ في الملف

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

الوثائق الأصلية

تاريخ الاطلاع على الوثائق .

الدليل المطلوب حفظه

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

مراجع رسمية

صفحات المصادر المرتبطة

بروتوكولات ذات صلة

فحوص قبل الاستنتاج

  • هل يمكن إعادة الاختيار دون سر؟
  • هل يشمل التعداد الصفحات والتكرار؟
  • هل الأصل منفصل عن البيانات المنظفة؟

أسئلة شائعة

هل تثبت 200 الشمول؟

لا. راجع الجسم والفلاتر والإجمالي والصفحات.

هل يلزم تنزيل القاعدة كلها؟

لا. اختر نطاقاً مفيداً ووثق حدوده.

هل تضمن البصمة الأرقام؟

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

كيف يمكنني استعادة مجموعة متقطعة؟

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

مرجع موثق

الكتابة عبر HTTP: التحقق من النسخة قبل استبدال الوثيقة

قد يقرأ محرران نسخة واحدة ثم يرسلان تصحيحين مختلفين. يتيح الشرط المسبق للخادم رفض كتابة تستند إلى تمثيل قديم. الحالات افتراضية: ⁦v1⁩ و⁦v2⁩ وسمان تعليميان وليسا رصداً لخدمة فعلية.

GET → "v1"ETag: "v2"PUT → 412If-Match: "v1" ≠ ETag: "v2"

قراءة ← تعديل متزامن ← رفض الكتابة: مثال افتراضي.

الكتابة عبر HTTP: التحقق من النسخة قبل استبدال الوثيقة
المرجعالقيمة أو الصيغةما الذي يحدده
PUT · If-Match: "v1"ETag: "v2" → 412تغيرت الوثيقة بعد قراءتها. تفشل المقارنة القوية في طلب ⁦PUT⁩ هذا؛ لا تستبدل النسخة الحالية. أعد قراءتها وافحص الاختلافات.
PUT · If-Match: "v2"ETag: "v2" → ✓يتطابق الوسمان القويان، فيسمح هذا الشرط بمواصلة المعالجة. لا يضمن ذلك الحالة ⁦200⁩ أو نجاح بقية الفحوص.
PUT · If-Match: W/"v2"ETag: "v2" → 412النص المعتم متطابق، لكن أحد الوسمين ضعيف. يتطلب ⁦If-Match⁩ مقارنة قوية فيفشل. حذف W/ لدى العميل لا ينشئ أداة تحقق قوية.
PUT · If-None-Match: *موجود → 412 / غائب → ✓في الكتابة، تشترط النجمة عدم وجود تمثيل حالي. يفشل الشرط عند وجوده، وتسمح حالة الغياب بمواصلة المعالجة.
GET · If-None-Match: W/"v2"ETag: "v2" → 304مع ⁦GET⁩ أو ⁦HEAD⁩ يستخدم ⁦If-None-Match⁩ مقارنة ضعيفة. يؤدي التطابق إلى ⁦304⁩؛ تُستخدم النسخة المحفوظة دون تلقي متن جديد.
428Precondition Requiredيشترط الخادم طلباً شرطياً. غياب الشرط يختلف عن ⁦412⁩ الذي يعني أن شرطاً مقدماً غير متحقق. يجب عدم تخزين استجابة ⁦428⁩ في الذاكرة المخبئية.

تجربة شرط مسبق

غيّر الطريقة والحالة والشرط. أدخل وسماً بين علامتي اقتباس أو قائمة تفصلها فواصل أو * وحدها. يُجرى التقييم في متصفحك. مع * أو غياب التمثيل، لا يُستخدم وسم ⁦ETag⁩ الحالي.

⁦412⁩: الشرط غير متحقق. لا تُنفذ العملية المطلوبة.

محاكاة تعليمية محلية: لا يُرسل أي طلب إلى واجهة ⁦API⁩ ولا تُحفظ البيانات.

ما يُحفظ في الملف

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

الوثائق الأصلية

تاريخ الاطلاع على الوثائق .

قراءة موسعة / تطبيق عملي

حفظ استعلام قابل لإعادة التنفيذ

يوفر API بيانات مفيدة، ولكن النتيجة تعتمد على الإعدادات والصفحة. يجب أن يحتفظ المجموعة بالطلب الكامل والشروط اللازمة لفهم الإجابة.

آخر تحديث في .

الفحوص ذات الأولوية

إرسال URL، الإعدادات، الحالة، النموذج والصفحة. التحكم في الفلاتر والحدود الحجمية والأخطاء التي يتم إرجاعها دون الكشف عن سر في السجلات.

أخطاء التفسير

يمكن أن يحتوي إجابة ناجحة على صفحة واحدة فقط من النتائج. تكرار الطلب في وقت لاحق قد يوفر حالة مختلفة إذا كانت البيانات قد تغيرت.

وثيقة العمل التي ينبغي حفظها

يرتبط سجل الاستقبال بالطلب، وتاريخ، والإجابة المحفوظة، والغطاء، والحد. يحدد كيفية استعادة أو التحقق من الاستخراج.