واجهة برمجة التطبيقات:امتدادات

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

إنشاء وحدة برمجية وتسجيلها

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

وحدات action البرمجية

يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعامل action الرئيسي فئة فرعية من ‎ApiBase . يجب أن تكون مسجلة في ‎extension.json مستخدمًا مفتاح ‎APIModules.

وحدات format البرمجية

يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعامل ‎format الرئيسي فئة فرعية من ‎ApiFormatBase. يجب أن تكون مسجلة في ‎extension.json مستخدمًا مفتاح ‎APIFormatModules. يندر للغاية أن يحتاج أي امتداد لإضافة وحدة format برمجية.

وحدات query البرمجية الفرعية

يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعاملات ‎prop أو ‎list أو ‎meta للوحدة ‎action=query فئة فرعية من ‎ApiQueryBase (لو لم تكن مستخدمة في صفة مولّد) أو ‎ApiQueryGeneratorBase (لو كانت مستخدمة في صفة مولّد). يجب أن تكون مسجلة في ‎extension.json مستخدمًا مفاتيح ‎APIPropModules أو ‎APIListModules أو ‎APIMetaModules.

في كافة الحالات، تصبح قيمة مفتاح التسجيل عنصر يحتوي على اسم الوحدة البرمجية (أي قيمة المعامل) في صفة مفتاح واسم الفئة في صفة قيمة. يجوز أيضًا تسجيل الوحدات البرمجية تسجيلًا شرطيًا مستخدمًا وصلات ‎ApiMain::moduleManager (للوحدات البرمجية من نوع action وformat) ومستخدمًا ‎ApiQuery::moduleManager (وحدات query البرمجية الفرعية).

التنفيذ

بادئة

في باني وحدتك البرمجية المخصصة لواجهة برمجة التطبيقات، حينما تستدعي ‎parent::__construct() يمكنك تحديد بادئة اختيارية لمعاملات وحدتك البرمجية. (في أعمال التوثيق المولّدة لهذه الوحدة البرمجية ستظهر هذه البادئة، لو وجدت، في أقواس في العنوان الرئيسي للوحدة البرمجية.) لو كانت وحدتك البرمجية هي وحدة برمجية فرعية لأغراض الاستفسار «query» سيتطلب الأمر وجود بادئة، منذ أن الجهاز العميل يمكنه استدعاء وحدات برمجية فرعية عدة مستخدمًا معاملاته الخاصة في طلب واحد. أما في الوحدات البرمجية لأغراض «action» و«format»، تصبح البادئة أمرًا اختياريًا.

معاملات

أغلب الوحدات البرمجية تتطلب وجود معاملات. هذه المعاملات معرفّة عن طريق تنفيذ ‎getAllowedParams(). القيمة الراجعة هي صفيف ترابطي الذي تكون فيه المفاتيح هي أسماء المعاملات (خالية من بادئات) والقيم هي إما قيمة متدرجة افتراضية للمعامل أو صفيف يعرّف خصائص المعامل مستخدمًا ثوابت ‎PARAM_* المعرفة في ‎ApiBase.

يبين المثال الصياغة النحوية وبعض من ثوابت ‎PARAM_* المعتادة.

	protected function getAllowedParams() {
		return [
			// معامل اختياري مع قيمة افتراضية
			'simple' => 'value',

			// معامل إلزامي
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// معامل يقبل عدة قيم من قائمة
			'variable' => [
				// المجموعة الافتراضية من القيم
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// كل القيم الممكنة
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// تشير إلى قبول عدة قيم
				ApiBase::PARAM_ISMULTI => true,
				// استخدم رسائل توثيق «حسب القيمة – per value»
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// معامل «حد - limit» قياسي. يفضل بوجه عام ألا يختلف عن هذا المعيار القياسي.
			'limit' => [
				ApiBase::PARAM_DFLT => 10,
				ApiBase::PARAM_TYPE => 'limit',
				ApiBase::PARAM_MIN => 1,
				ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
				ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
			],
		];
	}

توثّق المعاملات باستخدام آلية ميدياويكي لأعمال التدويل. طالع قسم #التوثيق لمزيد من التفاصيل.

التنفيذ والناتج

يذهب الكود البرمجي الذي ينفّذ بالفعل الوحدة البرمجية في طريقة ‎execute(). سيستخدم هذا الكود البرمجي بوجه عام ‎$this→extractRequestParams() للحصول على معاملات الإدخال، وسيستخدم ‎$this→getResult() للحصول على عنصر ‎ApiResult لإضافة أي خرج له.

يجب أن تستخدم الوحدات البرمجية الفرعية الملائمة لأغراض «الاستفسار - qurey» العنصر ‎$this→getPageSet() للوصول إلى مجموعة الصفحات التي سوف تعمل عليها.

سوف تحتاج أيضًا الوحدات البرمجية الفرعية لأغراض «query» التي يمكن استخدامها في صفة مولدات لتنفيذ ‎executeGenerator() الذي يمرر و‎ApiPageSet الذي يجب أن يجري ملئه بالصفحات المولدة. في هذه الحالة، يجب ألا يستخدم ‎ApiResult.

الحفظ المؤقت

توسم بصفة افتراضية ردود واجهة برمجة التطبيقات في صفة غير محفوظة حفظًا مؤقتًا ‎('Cache-Control: private')! في حالة الوحدات البرمجية لأغراض «التصرفات - action»، يمكنك أن تسمح بالحفظ المؤقت عن طريق استدعاء ‎$this→getMain()→setCacheMode(). إلا أن هذا الأمر يستلزم من الأجهزة العميلة تمرير معاملات ‎maxage أو ‎smaxage كي تمكّن في الواقع الحفظ المؤقت. يمكنك فرض الحفظ المؤقت أيضًا عن طريق استدعاء ‎$this→getMain()→setCacheMaxAge().

في حالة الوحدات البرمجية لأغراض «الاستفسار - query»، لا تستدعي تلك الطرق. يمكنك السماح بالحفظ المؤقت عن طريق بديل وهو تنفيذ ‎getCacheMode().

في كلتا الحالتين، تأكد من أن البيانات الخاصة غير معروضة.

التعامل مع الرموز

لو كانت وحدتك البرمجية لأغراض «التصرفات - action» تغيّر موقع الويكي بأي طريق كان، يجب أن تستلزم وجود رمز بأي نوع كان. كي يجري التعامل مع هذا الأمر آليًا، نفّذ طريقة ‎needsToken()، التي سوف ترجع الرمز الذي تستلزمه وحدتك البرمجية (في الغالب هو رمز التعديل ‎'csrf'). من ثمّ سوف يتولى الكود البرمجي الأساسي لواجهة برمجة التطبيقات التصديق آليًا على الرمز الذي يقدمه الجهاز العميل في طلبات واجهة برمجة التطبيقات في معامل من نوع ‎token.

إن لم تكن ترغب في استخدام رمز هو جزء من لب برمجي، بل إنه رمز مخصص لأغراض التحقق من التصريح الخاصة بك، استخدم وصلة ‎ApiQueryTokensRegisterTypes لتسجيل رمزك.

الوصول إلى قاعدة البيانات الرئيسية

لو كانت وحدتك البرمجية تصل إلى قاعدة بيانات رئيسية، يجب أن تنفّذ طريقة ‎isWriteMode() كي تحصل على ‎true.

الأخطاء المردودة

‎ApiBase يشتمل على طرق عدة لتنفيذ أعمال تحقق مختلفة، على سبيل المثال،

• لو كنت تحتاج للتأكيد على واحد بالتحديد من مجموعة من المعاملات مقدمة، استخدم ‎$this→requireOnlyOneParameter().
• لو كنت تحتاج لتأكيد أن على الأغلب واحد من مجموعة من المعاملات مقدمة، استخدم ‎$this→requireMaxOneParameter().
• لو كنت تحتاج لتأكيد أن على الأقل واحد من مجموعة من المعاملات مقدمة، استخدم ‎$this→requireAtLeastOneParameter().
• لو كنت تحتاج لتأكيد أن المستخدم يتمتع بحقوق بعينها، استخدم ‎$this→checkUserRightsAny().
• لو كنت تحتاج لتأكيد أن المستخدم يمكنه اتخاذ تصرف على صفحة محددة، استخدم ‎$this→checkTitleUserPermissions().
• لو كان المستخدم ممنوعًا (وكان هذا الأمر مهمًا لوحدتك البرمجية)، مرر عنصر ‎Block إلى ‎$this→dieBlocked().

إلا أنك سوف تتعرض غالبًا لحالات تحتاج فيها لرفع خطأ خاص بك. الطريقة المعتادة لعمل ذلك هي استدعاء ‎$this→dieWithError()، رغم أنه لو كان لديك ‎StatusValue مع معلومات الخطأ يمكنك تمرير هذا إلى ‎$this→dieStatus() بدلًا مما سلف.

لو كنت تحتاج لإصدار تحذير بدلًا من خطأ، استخدم ‎$this→addWarning() أو ‎$this→addDeprecation() لو كان الأمر تحذير في شأن تقادم.

التوثيق

واجهة برمجة التطبيقات موثّقة باستخدام آلية ميدياويكي لأعمال للتدويل. بوجه عام تحتوي الرسائل المطلوبة على أسماء افتراضية تستند إلى «مسار - path» الوحدة البرمجية. في حالات الوحدات البرمجية لأغراض «action» و«format»، يكون المسار هو ذات المسار الخاص باسم الوحدة البرمجية المستخدم أثناء التسجيل. في حالة الوحدات البرمجية الفرعية لأغراض «query»، هو الاسم تسبقه بادئة هي query+.

سوف تحتاج كل وحدة برمجية لرسالة ‎apihelp-$path-summary، والتي يجب أن تكون وصف من سطر واحد للوحدة البرمجية. لو تطلب الأمر نص مساعدة إضافي، يجوز استحداث ‎apihelp-$path-extended-description أيضًا. سوف يحتاج كل معامل رسالة ‎apihelp-$path-param-$name، وستحتاج المعاملات التي تستخدم ‎PARAM_HELP_MSG_PER_VALUE أيضًا إلى ‎apihelp-$path-paramvalue-$name-$value لكل قيمة.

لمزيد من التفاصيل عن توثيق واجهة برمجة التطبيقات، اذهب إلى ‎API:Localisation .

يجوز للامتدادات أيضًا أن توثّق وحدات واجهة برمجة تطبيقاتها الإضافية على mediawiki.org. يجب أن توجد هذه في صفحة الامتداد الرئيسية أو، لو تطلب الأمر مزيد من المساحة، على صفحات تحمل الاسم ‎Extension:<ExtensionName>/API أو صفحات فرعية منها (مثل ‎CentralAuth أو ‎MassMessage أو ‎StructuredDiscussions ). نطاق اسم واجهة برمجة التطبيقات محجوز لواجهة برمجة التطبيقات الموجودة في لب ميدياويكي البرمجي.

توسيع الوحدات البرمجية في اللب البرمجي

بدءً من إصدار ميدياويكي 1.14، من الممكن توسيع وظائف الوحدات البرمجية في اللب البرمجي باستخدام الوصلات التالية:

• APIGetAllowedParams - لإضافة قائمة معاملات الوحدة البرمجية أو تعديلها
• APIGetParamDescriptionMessages - لإضافة بيان معاملات الوحدة البرمجية أو تعديلها
• APIAfterExecute - لتنفيذ شيء ما بعد تنفيذ الوحدة البرمجية (إلا أن ذلك يكون قبل إخراج النتائج)
  • استخدم ‎APIQueryAfterExecute لأغراض الوحدات البرمجية ‎prop= و‎list= و‎meta=
    • لو كانت الوحدة البرمجية تعمل في وضع مولّد، سوف يجري استدعاء ‎APIQueryGeneratorAfterExecute بدلًا من ذلك

قائمة الامتدادات التي تحتوي على وظائف واجهة برمجة التطبيقات

طالع ‎تصنيف:امتدادات واجهة برمجة التطبيقات لترى مثال على الامتدادات التي تضيف إلى واجهة برمجة التطبيقات أو توسع عملها

اختبار امتدادك

• زر ‎api.php واذهب إلى المساعدة المولّدة لوحدتك البرمجية أو الوحدة البرمجية الفرعية لأغراض «الاستفسار - query» يجب أن تكون معلومات المساعدة لامتدادك صحيحة.
  • يجب أن تظهر معرفات الموارد الموحدة المقدمة في صفة أمثلة في ‎getExamplesMessages() تحت عنوان «أمثلة»، جرّب النقر عليها.
  • احذف معاملات معرفات الموارد الموحدة أو شفّرها في سطر الاستفسار، ثم تحقق من رد امتدادك.
• زر ‎Special:ApiSandbox واستكشف واجهة برمجة تطبيقاتك استكشافًا تفاعليًا.
• لتطلع على معلومات إضافية عن امتدادك:

api.php?action=paraminfo&modules=myext [جربها في ApiSandbox]