راهنمای واسط برنامه‌نویسی کاربردی مدیاویکی
این یک صفحهٔ مستندات برای واسط برنامه‌نویسی کاربردی مدیاویکی است که به‌طور خودکار ایجاد شده است.
مستندات و نمونه‌ها: https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page
General information
وضعیت: تمام ویژگی‌هایی که در این صفحه نمایش یافته‌اند باید کار بکنند، ولی رابط برنامه‌نویسی کاربردی کماکان در حال توسعه است، و ممکن است در هر زمان تغییر بکند. به عضویت فهرست پست الکترونیکی mediawiki-api-announce در بیایید تا از تغییرات باخبر شوید.
درخواست‌های معیوب: وقتی درخواست‌های معیوب به رابط برنامه‌نویسی کاربردی فرستاده شوند، یک سرایند اچ‌تی‌تی‌پی با کلید «MediaWiki-API-Erorr» فرستاده می‌شود و بعد هم مقدار سرایند و هم کد خطای بازگردانده شده هر دو به یک مقدار نسبت داده می‌شوند. برای اطلاعات بیشتر API: Errors and warnings را ببینید.
آزمایش: برای انجام درخواست‌های API آزمایشی Special:ApiSandbox را ببینید.
Request methods
Action API requests may use GET and POST methods. Prefer using the GET method, which allows requests to be routed to faster replica servers and responses to be cached, unless the length of the URL with parameters would exceed its length limit (commonly 8000 bytes), or a module only accepts POST requests.
Parameters for POST requests may be sent in the query part of the request URL (like in GET requests) and in the POST request body, and mixing both ways in one request is allowed. Certain parameters such as passwords must be sent in the request body. If the same parameter is sent as part of the URL and also in the request body, it must have the same value in both places.
Data types
Input to MediaWiki should be NFC-normalized UTF-8. MediaWiki may attempt to convert other input, but this may cause some operations (such as edits with MD5 checks) to fail.
Parameters that take multiple values are normally submitted with the values separated using the pipe character, e.g. param=value1|value2 or param=value1%7Cvalue2. If a value must contain the pipe character, use U+001F (Unit Separator) as the separator and prefix the value with U+001F, e.g. param=%1Fvalue1%1Fvalue2.
Some parameter types in API requests need further explanation:
- boolean
Boolean parameters work like HTML checkboxes: if the parameter is specified, regardless of value, it is considered true. For a false value, omit the parameter entirely.
- expiry
Expiry values may be relative (e.g. 5 months or 2 weeks) or absolute (e.g. 2014-09-18T12:34:56Z). For no expiry, use infinite, indefinite, infinity or never.
- timestamp
Timestamps may be specified in several formats, see the Timestamp library input formats documented on mediawiki.org for details. ISO 8601 date and time is recommended: 2001-01-15T14:56:00Z. The string now may be used to specify the current time.
Limits
Most API modules can accept up to ۵۰ inputs in multivalue parameters, and can return up to ۵۰۰ results per query (۵۰ results for slow queries).
For users with the apihighlimits right (ربات‌ها و مدیران), the limits are increased to ۵۰۰ inputs and ۵٬۰۰۰ results (۵۰۰ results for slow queries).
Templated parameters
Templated parameters support cases where an API module needs a value for each value of some other parameter. For example, if there were an API module to request fruit, it might have a parameter fruits to specify which fruits are being requested and a templated parameter {fruit}-quantity to specify how many of each fruit to request. An API client that wants 1 apple, 5 bananas, and 20 strawberries could then make a request like fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20.
پودمان اصلی
- منبع: MediaWiki
- مجوز: GPL-2.0-or-later
Specify the action to perform, the format of the response, and options that apply to all API modules.
- action
عملیاتی که باید انجام شود. این پارامتر باید جهت سهولت استفاده در اشکال‌زدایی، تحلیل، و مسیریابی یا فیلتر کردن درخواست، به عنوان بخشی از URL درخواست (نه بدنهٔ POST) ارسال شود.
- acquiretempusername
- دریافت یک نام کاربری برای کاربر موقت و ذخیرهٔ آن در نشست کنونی، در صورتی که ایجاد حساب موقت فعال باشد و کاربر کنونی از سامانه خارج شده باشد. اگر نامی از قبل ذخیره شده باشد، همان نام را بازمی‌گرداند.
- block
- بستن یک کاربر.
- changeauthenticationdata
- تغییر دادۀ اصالت‌سنجی برای کاربر کنونی
- changecontentmodel
- تغییر مدل محتوای یک صفحه
- checktoken
- بررسی اعتبار بلیط از action=query&meta=tokens.
- clearhasmsg
- پرچم
hasmsgرا برای کاربر جاری پاک کن. - clientlogin
- ورود به ویکی با استفاده از گردش کار تعاملی.
- compare
- تفاوت بین ۲ صفحه را بیابید.
- createaccount
- ایجاد یک حساب تازه کاربری
- delete
- حذف صفحه
- edit
- ایجاد و ویرایش صفحه
- emailuser
- ایمیل به کاربر
- expandtemplates
- گسترش همه الگوها در ویکی نبشته
- feedcontributions
- خوراک مشارکت‌های یک کاربر را برمی‌گرداند.
- feedrecentchanges
- خوراک تغییرات اخیر را برمی‌گرداند.
- feedwatchlist
- برگرداندن خوراک فهرست پیگیری.
- filerevert
- واگردانی فایل به یک نسخه قدیمی
- help
- نمایش راهنمای پودمان‌های مشخص‌شده.
- imagerotate
- چرخاندن یک یا چند تصویر
- import
- Import a page from another wiki, or from an XML file.
- languagesearch
- Search for language names in any script.
- linkaccount
- Link an account from a third-party provider to the current user.
- login
- Log in and get authentication cookies.
- logout
- خروج به همراه پاک نمودن اطلاعات این نشست
- managetags
- Perform management tasks relating to change tags.
- mergehistory
- ادغام تاریخچه‌های صفحه
- move
- انتقال صفحه
- opensearch
- جستجو در ویکی بااستفاده از پروتکل اوپن‌سرچ.
- options
- تغییر ترجیحات کاربر جاری
- paraminfo
- Obtain information about API modules.
- parse
- Parses content and returns parser output.
- patrol
- گشت‌زنی یک صفحه یا نسخهٔ ویرایشی.
- protect
- تغییر سطح محافظت صفحه
- purge
- Purge the cache for the given titles.
- query
- Fetch data from and about MediaWiki.
- removeauthenticationdata
- Remove authentication data for the current user.
- resetpassword
- Send a password reset email to a user.
- revisiondelete
- Delete and undelete revisions.
- rollback
- Undo the last edit to the page.
- rsd
- Export an RSD (Really Simple Discovery) schema.
- setnotificationtimestamp
- Update the notification timestamp for watched pages.
- setpagelanguage
- Change the language of a page.
- tag
- Add or remove change tags from individual revisions or log entries.
- unblock
- بازکردن کاربر.
- undelete
- احیای نسخه‌های یک صفحهٔ حذف‌شده.
- unlinkaccount
- Remove a linked third-party account from the current user.
- upload
- بارگذاری یک پرونده یا دریافت وضعیت بارگذاری‌های در انتظار.
- userrights
- تغییر گروهی که کاربر در آن عضو است.
- validatepassword
- Validate a password against the wiki's password policies.
- watch
- Add or remove pages from the current user's watchlist.
- cspreport
- داخلی Used by browsers to report violations of the Content Security Policy. This module should never be used, except when used automatically by a CSP compliant web browser.
- stashedit
- داخلی Prepare an edit in shared cache.
- یکی از مقدارهای زیر: acquiretempusername، block، changeauthenticationdata، changecontentmodel، checktoken، clearhasmsg، clientlogin، compare، createaccount، delete، edit، emailuser، expandtemplates، feedcontributions، feedrecentchanges، feedwatchlist، filerevert، help، imagerotate، import، languagesearch، linkaccount، login، logout، managetags، mergehistory، move، opensearch، options، paraminfo، parse، patrol، protect، purge، query، removeauthenticationdata، resetpassword، revisiondelete، rollback، rsd، setnotificationtimestamp، setpagelanguage، tag، unblock، undelete، unlinkaccount، upload، userrights، validatepassword، watch، cspreport، stashedit
- پیش‌فرض: help
- format
فرمت خروجی.
- json
- خروجی داده در قالب جی‌سان.
- jsonfm
- خروجی داده در قالب جی‌سان (چاپ زیبا در اچ‌تی‌ام‌ال).
- none
- بیرون‌ریزی هیچ.
- php
- Output data in serialized PHP format.
- phpfm
- Output data in serialized PHP format (pretty-print in HTML).
- rawfm
- Output data, including debugging elements, in JSON format (pretty-print in HTML).
- xml
- Output data in XML format.
- xmlfm
- Output data in XML format (pretty-print in HTML).
- یکی از مقدارهای زیر: json، jsonfm، none، php، phpfm، rawfm، xml، xmlfm
- پیش‌فرض: jsonfm
- maxlag
بیشینهٔ تأخیر زمانی می‌تواند استفاده شود که مدیاویکی روی یک خوشهٔ همگون‌سازی‌شدهٔ پایگاه داده نصب شده باشد. برای جلوگیری از اینکه اقدامات باعث تأخیر همگون‌سازی بیشتر در سایت شوند، این پارامتر می‌تواند کارخواه را تا زمانی که تأخیر همگون‌سازی کمتر از مقدار مشخص‌شده باشد، منتظر نگه دارد. در صورت تأخیر بیش از حد، کد خطای maxlag همراه با پیامی مانند Waiting for $host: $lag seconds lagged بازگردانده می‌شود.
برای اطلاعات بیشتر، راهنما: پارامتر Maxlag را ببینید.- نوع: عدد صحیح
- smaxage
تنظيم
s-maxageسرآیند کنترل حافضهٔ نهان HTTP بر اين تعداد ثانيه‌ها. خطاها هرگز در حافظه نهان نمی‌شوند.- نوع: عدد صحیح
- The value must be no less than ۰.
- پیش‌فرض: 0
- maxage
تنظيم
s-maxageسرآیند کنترل حافضهٔ نهان HTTP بر اين تعداد ثانيه‌ها. خطاها هرگز در حافظه نهان نمی‌شوند.- نوع: عدد صحیح
- The value must be no less than ۰.
- پیش‌فرض: 0
- assert
بررسی اینکه اگر روی user تنظیم شده باشد، کاربر وارد شده باشد (از جمله احتمالاً به عنوان کاربر موقت)، اگر روی anon تنظیم شده باشد، وارد نشده باشد، یا اگر روی bot باشد، اختیارات کاربر ربات را داشته باشد.
- یکی از مقدارهای زیر: anon، bot، user
- assertuser
تأیید این که کاربر کنونی همان کاربر نام‌دار است.
- نوع: کاربر، توسط هریک از نام کاربری و حساب کاربری موقت
- requestid
هر مقداری که در اینجا وارد شود در پاسخ گنجانده می‌شود. ممکن است برای تمايز بين درخواست‌ها بکار رود.
- servedby
نام ميزبانی که درخواست را سرويس داده در نتايج گنجانده شود.
- نوع: بولی (جزئیات)
- curtimestamp
برچسب زمان کنونی را در نتیجه قرار دهید.
- نوع: بولی (جزئیات)
- responselanginfo
گنجاندن زبان مورد استفاده برای userlang و errorlang در نتیجه.
- نوع: بولی (جزئیات)
- origin
هنگام دسترسی به API با استفاده از درخواست AJAX فرادامنه‌ای (CORS)، این مقدار را روی دامنهٔ مبدأ تنظیم کنید. این پارامتر باید در هر درخواست پیش‌پرواز (pre-flight) گنجانده شود، و بنابراین باید بخشی از URL درخواست باشد (نه بدنهٔ POST).
برای درخواست‌های احرازهویت‌شده، این مقدار باید دقیقاً با یکی از مبدأها در سرآیند
Originمطابقت داشته باشد، بنابراین باید روی چیزی مانند https://en.wikipedia.org یا https://meta.wikimedia.org تنظیم شود. اگر این پارامتر با سرآیندOriginمطابقت نداشته باشد، پاسخ ۴۰۳ بازگردانده خواهد شد. اگر این پارامتر با سرآیندOriginمطابقت داشته باشد و مبدأ مجاز باشد، سرآیندهایAccess-Control-Allow-OriginوAccess-Control-Allow-Credentialsتنظیم خواهند شد.برای درخواست‌های احرازهویت‌نشده، مقدار * را مشخص کنید. این کار باعث تنظیم سرآیند
Access-Control-Allow-Originمی‌شود، اما مقدارAccess-Control-Allow-Credentialsبرابر باfalseخواهد بود و تمامی داده‌های اختصاصی کاربر محدود خواهند شد.- crossorigin
هنگام دسترسی به API با استفاده از درخواست AJAX فرادامنه‌ای (CORS) و استفاده از ارائه‌دهندهٔ نشستی که در برابر حملات جعل درخواست بین‌سایتی (CSRF) ایمن است (مانند OAuth)، از این به جای
origin=*استفاده کنید تا درخواست احرازهویت‌شده انجام شود (یعنی از سامانه خارج نشود). این پارامتر باید در هر درخواست پیش‌پرواز (pre-flight) گنجانده شود، و بنابراین باید بخشی از URL درخواست باشد (نه بدنهٔ POST).توجه داشته باشید که بیشتر ارائه‌دهندگان نشست، از جمله نشست‌های استاندارد مبتنی بر کوکی، از CORS احرازهویت‌شده پشتیبانی نمی‌کنند و نمی‌توان از آن‌ها با این پارامتر استفاده کرد.
- نوع: بولی (جزئیات)
- uselang
زبانی که برای ترجمهٔ پیام‌ها استفاده می‌شود. action=query&meta=siteinfo&siprop=languages فهرستی از کدهای زبان را بازمی‌گرداند. می‌توانید user را برای استفاده از ترجیح زبان کاربر کنونی یا content را برای استفاده از زبان محتوای این ویکی مشخص کنید.
- پیش‌فرض: user
- variant
گونهٔ زبان. تنها در صورتی کار می‌کند که زبان مبنا از تبدیل گونه پشتیبانی کند.
- errorformat
قالبی به‌منظور استفاده برای متن خروجی هشدار و خطا
- plaintext
- ویکی‌متن با برچسب‌های اچ‌تی‌ام‌ال حذف‌شده و موجودیت‌های جایگزین‌شده.
- wikitext
- ویکی‌متن تجزیه‌نشده.
- html
- HTML
- raw
- کلید پیام و پارامترها.
- none
- بدون متن خروجی، فقط شناسه‌های خطا.
- bc
- قالب مورد استفاده تا پیش از مدیاویکی ۱.۲۹. از errorlang و errorsuselocal چشم‌پوشی می‌شود.
- یکی از مقدارهای زیر: bc، html، none، plaintext، raw، wikitext
- پیش‌فرض: bc
- errorlang
زبانی که برای هشدارها و خطاها استفاده می‌شود. action=query&meta=siteinfo&siprop=languages فهرستی از کدهای زبان را بازمی‌گرداند. content را برای استفاده از زبان محتوای این ویکی یا uselang را برای استفاده از همان مقدار پارامتر uselang مشخص کنید.
- پیش‌فرض: uselang
- errorsuselocal
در صورت وارد شدن، متن خطاها از پیام‌های سفارشی‌سازی‌شدهٔ محلی از فضای نام مدیاویکی استفاده خواهند کرد.
- نوع: بولی (جزئیات)
- راهنما برای پودمان اصلی.
- api.php?action=help [باز کردن در صفحهٔ تمرین]
- همهٔ راهنماها در یک صفحه.
- api.php?action=help&recursivesubmodules=1&toc [باز کردن در صفحهٔ تمرین]
اعتبار
API developers:
- Yuri Astrakhan (creator, lead developer Sep 2006–Sep 2007)
- Roan Kattouw (lead developer Sep 2007–2009)
- Victor Vasiliev
- Bryan Tong Minh
- Sam Reed
- Brad Jorsch (lead developer 2013–2020)
Please send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org or file a bug report at https://phabricator.wikimedia.org/.