واجهة برمجة التطبيقات:دليل توجيهي
| هذه الصفحة جزء من توثيق واجهة برمجة تطبيقات ميدياويكي التي تحمل اسم Action. |
سوف تتعرف في هذا الدليل التوجيهي على واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي وكيفية استخدامها وطلب الصيغة وإجراء استفسار بسيط وأمثلة على المشاريع التي تستعين بواجهة برمجة التطبيقات لتطبيق Action.
نظرة عامة على واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي
إن واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي هي خدمة وب من نوع REST تسمح للمستخدمين بإجراء أعمال ويكي معينة مثل إنشاء الصفحات والتصديق والتحليل اللغوي والبحث وخلافه. واجهة برمجة التطبيقات:الصفحة الرئيسية هي نقطة بداية طيبة كي تستوعب واجهة برمجة التطبيقات هذه.
يرسل برنامجك طلبات إلى واجهة برمجة التطبيقات للوصول إلى سمات الويكي. مثال ذلك تسجيل الدخول إلى موقع ويكي أو إنشاء صفحة وتعديلها أو البحث عن عنوان أو البحث عن نص في المحتوى أو تحليل المحتوى لغويا. إن واجهة برمجة التطبيقات لتطبيق Action متاحة للمطورين من الغير ومطوري امتدادات ويكيميديا وإداري مواقع الويكي.
توجد في الشريط الجانبي يسار هذه الصفحة لهذه الصفحة عدة سمات تدعمها واجهة برمجة التطبيقات، مقسمة حسب تصنيفها. قبل إرسال طلبات إلى خادم ويكي، يرجى أولًا قراءة صفحات الموجز مثل صيغ البيانات و الأخطاء والتحذيرات وكذلك الأسئلة المتكررة في شأن واجهة برمجة التطبيقات التي تحمل الاسم Action.
كيفية استخدام واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي
يمكنك طلب بيانات من جانب البرنامج العميل إلى الخادم مستخدمًا إتش تي بي بي والحصول على رد في صيغة قياسية (عادة ما تكون جسون). يتكون أي طلب من نقطة نهاية ومجموعة من المتغيرات. يوجد نوعين اثنين من الطلبات التي يمكن إرسالها: طلب GET أو طلب POST. فيما يخص طلبات GET، قد يحتوي المتغير على سطر استعلام في عنوان معرف الموارد الموحد. أما طلبات POST، فيجب أن تصاغ المتغيرات في صيغة جسون.
صيغة الطلب
تحتوي كافة مواقع الويكي التابعة لويكيميديا نقاط نهاية صيغت في هذه الصيغة http://example.org/w/api.php. كي تعمل على موقع ميدياويكي الرئيسي أو ويكيبيديا الإنكليزية، استخدم نقطة النهاية المعنية. على سبيل المثال، توجد نقطة نهاية ويكيبيديا الإنكليزية في https://en.wikipedia.org/w/api.php. من أجل اختبار الحسابات الجديدة أو اختبار تعديلات على صفحات، استخدم نقطة نهاية ويكي الاختبار https://test.wikipedia.org/w/api.php.
أضف إلى سطر الاستعلام في معرف الموارد الموحد المتغير action. يخبر هذا المتغير واجهة برمجة التطبيقات ما هو التصرف المطلوب تنفيذه. أكثر التصرفات شيوعًا هو query (ربما يحتوي معرف الموارد الموحد على action=query)، الذي يسمح بجلب البيانات من موقع الويكي.) بعد المتغير action، أضف متغير آخر كي تشير إلى ما هو نوع وحدة الاستعلام البرمجية من بين الثلاث المتاحة التي ترغب في تنفيذها:
prop- الحصول على خصائص صفحاتlist- سرد قائمة صفحات ينطبق عليها معيار معينmeta- الحصول على معلومات فوقية تتعلق بموقع الويكي والمستخدم
في الختام، أضف المتغير format، الذي يبلغ واجهة برمجة التطبيقات ما هي الصيغة التي يجب أن ترسل النتائج بها. الصيغة التي نوصي بها هي جسون. كانت واجهة برمجة التطبيقات تدعم صيغ خرج أخرى في السابق، إلا أننا لا نوصي بها عمومًا.
استعلام بسيط
هيا بنا ننظر إلى مثال على استعلام بسيط كي نستوعب ما هي هيئة طلب GET معتاد وهيئة الرد في سياق واجهة برمجة التطبيقات التي تحمل الاسم Action.
هيا نبحث عن عنوان في موقع ويكي. سوف نستخدم الوحدة البرمجية search الموثقة في صفحة API:Search.
طلب GET
كي تبحث عن عناوين صفحات أو محتوى يطابق Craig Noone، سوف يكون معرف الموارد الموحد لطلب GET في صيغة إتش تي تي بي كما يلي:
تفسير كل جزء من معرف الموارد الموحد:
http://en.wikipedia.org/w/api.phpهو نقطة النهاية الرئيسية. في هذه الحالة هي ويكيبيديا الإنكليزية.action=queryيعني جلب البيانات من موقع الويكي.list=searchيعني الحصول على قائمة بالصفحات التي تطابق معيار ما.srsearch=Craig%20Nooneيشير إلى عنوان الصفحة أو المحتوى المطلوب البحث عنه. يشير%20إلى محرف مسافة في معرف الموارد الموحد.format=jsonيشير إلى خرج جسون، وهو صيغة الخرج التي نوصي بها.
النتيجة
النتيجة هي وثيقة في صيغة جسون تحتوي على قائمة بعناوين الصفحات التي تطابق المعيار Craig Noone:
{
"batchcomplete": "",
"continue": {
"sroffset": 10,
"continue": "-||"
},
"query": {
"searchinfo": {
"totalhits": 210
},
"search": [
{
"ns": 0,
"title": "Craig Noone",
"pageid": 18846922,
"size": 22548,
"wordcount": 1771,
"snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
"timestamp": "2018-11-02T22:25:45Z"
},
{
"ns": 0,
"title": "Noone",
"pageid": 32906333,
"size": 553,
"wordcount": 64,
"snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to: <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
"timestamp": "2015-08-16T05:16:17Z"
}
...
]
}
}
أمثلة على مشاريع تستخدم واجهة برمجة التطبيقات التي تحمل الاسم Action
بعض الأمثلة على مشاريع ويكيميديا تستخدم واجهة برمجة التطبيقات لتطبيق Action:
- تطبيق ويكيبيديا لأجهزة iOS، حيث أن أحد السمات هي البحث عن صفحات الويكي قرب موقعك.
- البوتات التي تعمل على موقع ويكي. إن باي ويكي بوت هو بنية بوت كتبت بلغة بايثون تعمل على واجهة برمجة تطبيقات ميدياويكي التي يستخدمها الكثير من مطوري البوتات.
- استخدام واجهة برمجة التطبيقات في تمثيل البيانات المجلوبة من موقع ويكي تمثيلًا مرئيًا. مثل التمثيل المرئي المحبوب الذي يعرض التعديلات في لحظتها التي تجري على ويكيبيديا.
ملاحظات إضافية
- تستخدم عدة مواقع ميدياويكي. ربما تشغّل جميعها نسخة مختلفة من ميدياويكي وبالتالي نسخة أخرى من واجهة برمجة التطبيقات. يجوز أن تصبح بعض متغيرات الوحدات البرمجية التي تدعمها نسخة ما متقادمة في نسخ أخرى أو مرفوعة منها. يمكنك أن تتعرف على المزيد عن هذا الأمر في أعمال توثيق كل واحدة برمجية عن طريق وحدة المساعدة البرمجية لواجهة برمجة التطبيقات.
- لو كنت ترغب في إجراء عدد كبير من طلبات واجهة برمجة التطبيقات، وربما تشغيل بوتات كثيرة النشاط، تحدث مع إداري الويكي مسبقًا، حتى لا يمنعوك. طالع قائمة إداريين مشاريع ويكيميديا. طالع المزيد عن هذا الموضوع في صفحة API:Etiquette.
- قد تتطلب كافة التصرفات التي تعدّل بيانات مثل تسجيل قيود أو التعديل أو نقل صفحات وكذلك متابعة التغييرات أو مراقبتها الحصول على رموز. سوف يتعين عليك الحصول على الرموز مستخدمًا واجهة برمجة التطبيقات:Tokens كي تتمكن من المتابعة.
الموارد
- استخدم Special:APISandbox كي تجرّب واجهة برمجة التطبيقات لتطبيق Action. يمكنك تجربة التصرفات المدعومة وتحديد قيمة أحد المتغيرات وإرسال الطلبات إلى واجهة برمجة التطبيقات كي ترى نتائج ذلك في ذات الصفحة.
- مراكمات ويكيميديا حتى يمكنك التعامل معها محليًا.
- طالع الدروس التعليمية: مقدمة في استخدام واجهة برمجة التطبيقات وكذلك ما هي REST – تفسير بسيط للمبتدئين.
- مساعدة واجهة برمجة تطبيقات ميدياويكي تقدم توثيق مولّد آليًا لواجهة برمجة التطبيقات لكافة الوحدات البرمجية المدعومة.
- واجهة برمجة التطبيقات:الصفحة الرئيسية يقدم نظرة عامة على واجهة برمجة التطبيقات لتطبيق Action.
- مقدمة إلى واجهة برمجة تطبيقات ميدياويكي قدمها User:Roan_Kattouw_(WMF) في منافسة برمجة سان فرانسيسكو 2012. هذا الدليل التعليمي يتماشى مع المقطع المرئي.
- غت هب: عروض توضيحية لواجهة برمجة تطبيقات ميدياويكي