API:Tutorial/ar

سوف تتعرف في هذا الدليل التوجيهي على واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي وكيفية استخدامها وطلب الصيغة وإجراء استفسار بسيط وأمثلة على المشاريع التي تستعين بواجهة برمجة التطبيقات لتطبيق Action.

شاهد تطبيقات تقديمية على مصنع الأدوات «Toolforge»

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

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

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

كيفية استخدام واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي
يمكنك طلب بيانات من جانب البرنامج العميل إلى الخادم مستخدمًا إتش تي بي بي والحصول على رد في صيغة قياسية (عادة ما تكون جسون). يتكون أي طلب من نقطة نهاية ومجموعة من المتغيرات. يوجد نوعين اثنين من الطلبات التي يمكن إرسالها: طلب GET أو طلب POST. فيما يخص طلبات GET، قد يحتوي المتغير على سطر استعلام في عنوان معرف الموارد الموحد. أما طلبات POST، فيجب أن تصاغ المتغيرات في صيغة جسون.

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

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


 * - الحصول على خصائص صفحات
 * - سرد قائمة صفحات ينطبق عليها معيار معين
 * - الحصول على معلومات فوقية تتعلق بموقع الويكي والمستخدم

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

استعلام بسيط
هيا بنا ننظر إلى مثال على استعلام بسيط كي نستوعب ما هي هيئة طلب GET معتاد وهيئة الرد في سياق واجهة برمجة التطبيقات التي تحمل الاسم Action.

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

طلب GET
كي تبحث عن عناوين صفحات أو محتوى يطابق ، سوف يكون معرف الموارد الموحد لطلب GET في صيغة إتش تي تي بي كما يلي:تفسير كل جزء من معرف الموارد الموحد:


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

النتيجة
النتيجة هي وثيقة في صيغة جسون تحتوي على قائمة بعناوين الصفحات التي تطابق المعيار Craig Noone:

أمثلة على مشاريع تستخدم واجهة برمجة التطبيقات التي تحمل الاسم Action
Some example of projects in Wikimedia that use Action API:


 * Wikipedia iOS App, in which one of the features is to search for wiki pages near your location.
 * Bots that operate on a wiki. Pywikibot is a bot framework written in Python that interfaces with MediaWiki API which a lot of bot developers use.
 * API use in visualizing data obtained from a wiki. Such as this neat visualization that shows real time edits made on Wikipedia.

Additional notes

 * Several sites are using MediaWiki. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
 * If you want to make a lot of API calls, and perhaps run very busy and active bots, talk to wiki admins ahead of time, so they do not block you. See list of Administrators of Wikimedia projects. Read more about this topic on.
 * All data modifying actions such as logging, editing or moving a page, and watching or patrolling changes would require tokens. You would need to obtain tokens via to proceed further.

Resources

 * Use Special:APISandbox to experiment with the Action API. You can play around with supported actions, specify a value for parameters, and send requests to the API to see the results on the same page.
 * Wikimedia dumps so you can work with them locally.
 * Read through tutorials: An Introduction to API's and What is REST — A Simple Explanation for Beginners.
 * MediaWiki API help provides auto-generated API documentation of all supported modules.
 * provides an overview of the Action API.
 * Introduction to the MediaWiki API by User:Roan_Kattouw_(WMF) at the San Francisco Hackathon, 2012. This tutorial guide goes along with the video.
 * GitHub: MediaWiki API Demos