עזרה של MediaWiki API

זהו דף תיעוד של API שנוצר באופן אוטומטי.

תיעוד ודוגמאות: https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page

יחידה ראשית

מקור: MediaWiki
רישיון: GPL-2.0-or-later

מצב: ה־API של מדיה־ויקי הוא ממשק ותיק ויציב שנתמך ומשתפר באופן סדיר. אף שאנחנו משתדלים להימנע מכך, לעיתים עלינו לבצע שינויים שעלולים לשבש דברים בפונקציונליות הזאת; באפשרותך לעשות מינוי לרשימת התפוצה mediawiki-api-announce כדי לקבל הודעות על עדכונים.

בקשות שגויות: כשבקשות שגויות נשלחות ל־API, יישלח כותר HTTP עם המפתח "MediaWiki-API-Error", ואז גם הערך של הכותרת וגם קוד השגיאה יוגדרו לאותו ערך. למידע נוסף, אפשר לעיין בדף API:שגיאות ואזהרות.

בדיקה: לבדיקה קלה יותר של בקשות, אפשר להשתמש בארגז החול של API.

פרמטרים:

action

איזו פעולה לבצע.

block: חסימת משתמש.
changeauthenticationdata: שינוי נתוני אימות עבור המשתמש הנוכחי.
changecontentmodel: שינוי מודל התוכן של דף
checktoken: בדיקת התקינות של האסימון מ־action=query&meta=tokens.
clearhasmsg: מנקה את דגל hasmsg עבור המשתמש הנוכחי.
clientlogin: כניסה לוויקי באמצעות זרימה הידודית.
compare: קבלת ההבדל בין שני דפים.
createaccount: יצירת חשבון משתמש חדש.
delete: מחיקת דף.
edit: יצירה ועריכה של דפים.
emailuser: שליחת דוא"ל למשתמש.
expandtemplates: מרחיב את כל התבניות בתוך קוד הוויקי.
feedcontributions: מחזיר הזנת תרומות משתמש.
feedrecentchanges: מחזיר הזנת שינויים אחרונים.
feedwatchlist: מחזיר הזנת רשימת מעקב.
filerevert: שחזור קובץ לגרסה ישנה יותר.
help: הצגת עזרה עבור היחידות שצוינו.
imagerotate: סיבוב של תמונה אחת או יותר.
import: ייבוא דף מוויקי אחר או מקובץ XML.
linkaccount: קישור חשבון של ספק צד־שלישי למשתמש הנוכחי.
login: כניסה וקבלת עוגיות אימות.
logout: יציאה וניקוי של נתוני הפעילות.
managetags: ביצוע פעולות ניהוליות הקשורות בתגי שינוי.
mergehistory: מיזוג גרסאות של דפים.
move: העברת דף.
opensearch: חיפוש בוויקי בפרוטוקול OpenSearch.
options: שינוי העדפות של המשתמש הנוכחי.
paraminfo: קבלת מידע על יחידות של API.
parse: מפענח את התוכן ומחזיר פלט מפענח.
patrol: לנטר דף או גרסה.
protect: לשנות את רמת ההגנה של דף.
purge: ניקוי המטמון לכותרות שניתנו.
query: אחזור נתונים ממדיה־ויקי ועליה.
removeauthenticationdata: הסרת נתוני אימות עבור המשתמש הנוכחי.
resetpassword: שליחת דוא"ל איפוס סיסמה למשתמש.
revisiondelete: מחיקה ושחזור ממחיקה של גרסאות.
rollback: ביטול העריכה האחרונה לדף.
rsd: יצוא סכמת RSD‏ (Really Simple Discovery).
setnotificationtimestamp: עדכון חותם־הזמן של ההודעה עבור דפים במעקב.
setpagelanguage: שינוי השפה של דף.
tag: הוספה או הסרה של תגים מגרסאות בודדות או רשומות יומן בודדות.
unblock: שחרור משתמש מחסימה.
undelete: שחזור גרסאות של דף מחוק.
unlinkaccount: ביטול קישור של חשבון צד־שלישי מהמשתמש הנוכחי.
upload: העלאת קובץ, או קבלת מצב ההעלאות הממתינות.
userrights: שינוי חברות בקבוצות של המשתמש.
validatepassword: לבדוק תקינות סיסמה אל מול מדיניות הסיסמאות של הוויקי.
watch: להוסיף דפים לרשימת המעקב של המשתמש הנוכחי או הסרתם ממנה.
tokens: מיושן. קבלת אסימונים לפעולות שמשנות נתונים.
cspreport: פנימי. משמש דפדפנים לדיווח הפרות של מדיניות אבטחת תוכן. המודול הזה לעולם לא ישמש אלא אם הוא משמש עם דפדפן תומך CSP.
stashedit: פנימי. הכנת עריכה במטמון משותף.

אחד מהערכים הבאים: block, changeauthenticationdata, changecontentmodel, checktoken, clearhasmsg, clientlogin, compare, createaccount, delete, edit, emailuser, expandtemplates, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, help, imagerotate, import, 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, tokens, cspreport, stashedit

ברירת המחדל: help

format

תסדיר הפלט.

json: לפלוט נתונים בתסדיר JSON.
jsonfm: לפלוט נתונים בתסדיר JSON (עם הדפסה יפה ב־HTML).
none: לא לפלוט שום דבר.
php: לפלוט נתונים בתסדיר PHP מוסדר.
phpfm: לפלוט נתונים בתסדיר PHP מוסדר (עם הדפסה יפה ב־HTML).
rawfm: לפלוט את הנתונים, כולל אלמנטים לניפוי שגיאות, בתסדיר JSON (עם הדפסה יפה ב־HTML).
xml: לפלוט נתונים בתסדיר XML.
xmlfm: לפלוט נתונים בתסדיר XML (עם הדפסה יפה ב־HTML).

אחד מהערכים הבאים: json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm

ברירת המחדל: jsonfm

maxlag

שיהוי מרבי יכול לשמש כשמדיה־ויקי מותקנת באשכול עם מסד נתונים משוכפל. כדי לחסוך בפעולות שגורמות יותר שיהוי בשכפול אתר, הפרמטר הזה יכול לגרום ללקוח להמתין עד ששיהוי השכפול יורד מתחת לערך שצוין. במקרה של שיהוי מוגזם, קוד השגיאה maxlag מוחזר עם הודעה כמו Waiting for $host: $lag seconds lagged.
ר' מדריך למשתמש: פרמטר maxlag למידע נוסף.

סוג: מספר שלם

smaxage

להגדיר את כותר s-maxage לבקרת מטמון HTTP‏ למספר כזה של שניות. שגיאות אף פעם לא מוטמנות.

סוג: מספר שלם

ברירת המחדל: 0

maxage

להגדיר את כותר max-age לבקרת מטמון HTTP‏ למספר כזה של שניות. שגיאות אף פעם לא מוטמנות.

סוג: מספר שלם

ברירת המחדל: 0

assert

לוודא שהמשתמש נכנס לחשבון אם זה מוגדר ל־user, שלא נכנס לחשבון אם מוגדר anon, או שיש לו הרשאת המשתמש "בוט" אם זה bot.

אחד מהערכים הבאים: anon, bot, user

assertuser

לוודא שהמשתמש הנוכחי הוא המשתמש ששמו ניתן.

סוג: משתמש, בצורה הבאה: שם משתמש

requestid

כל ערך שיינתן כאן ייכלל בתשובה. אפשר להשתמש בזה כדי להבדיל בין בקשות.

servedby

לכלול את שם המארח ששירת את הבקשה בתוצאות.

סוג: בוליאני (פרטים)

curtimestamp

לכלול את חותם־הזמן הנוכחי בתוצאה.

סוג: בוליאני (פרטים)

responselanginfo

לכלול את השפות שמשמשות ל־uselang ול־errorlang בתוצאה.

סוג: בוליאני (פרטים)

origin

בעת גישה ל־API עם בקשת AJAX חוצה תחומים (CORS), יש להציב כאן את התחום שהבקשה יוצאת ממנו. זה היה להיות כלול בכל בקשה מקדימה, ולכן הוא חייב להיות חלק מה־URI של הבקשה (לא גוף ה־POST).

עבור בקשות מאומתות, זה חייב להיות תואם במדויק לאחד המקורות בכותרת Origin, כך שזה צריך להיות מוגדר למשהו כמו https://en.wikipedia.org או https://meta.wikimedia.org. אם הפרמטר הזה אינו תואם לכותרת Origin, תוחזר תשובת 403. אם הפרמטר הזה תורם לכותרת Origin והמקור נמצא ברשימה הלבנה, תוגדרנה הכותרות Access-Control-Allow-Origin ו־Access-Control-Allow-Credentials.

עבור בקשות בלתי־מאומתות, יש לציין את הערך *. זה יגרום לכותרת להיות Access-Control-Allow-Origin, אבל Access-Control-Allow-Credentials תהיה false וכל הנתונים הייחודיים למשתמש יהיו מוגבלים.

uselang

באיזו שפה להשתמש לתרגומי הודעות. הקריאה action=query&meta=siteinfo עם siprop=languages מחזירה רשימת קודים. ציון user כדי להשתמש בהעדפת השפה של המשתמש הנוכחי, וציון content להשתמש בשפת התוכן של הוויקי הזה.

ברירת המחדל: user

errorformat

תסדיר לשימוש בפלט טקסט אזהרות ושגיאות.

plaintext: קוד ויקי ללא תגי HTML ועם ישויות מוחלפות.
wikitext: קוד ויקי לא מפוענח.
html: קוד HTML.
raw: מפתח הודעה ופרמטרים.
none: ללא פלט טקסט, רק הודעות השגיאה.
bc: התסדיר ששימש לפני מדיה־ויקי 1.29. התעלמות מ־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 [פתיחה בארגז חול]

הרשאות:

writeapi: שימוש ב־API לשינוי דפים; הוענקו ל: all, user וגם bot
apihighlimits: להשתמש במגבלות גבוהות יותר בשאילתות API (שאילתות אטיות: 500; שאילתות מהירות: 5000). המגבלות לשאילתות אטיות חלות גם על פרמטרים מרובי־ערכים.; הוענקו ל: bot וגם sysop

סוגי נתונים

קלט למדיה־ויקי אמור להיות UTF-8 מנורמת לפי NFC. מדיה־ויקי ויקי יכולה לנסות להמיר קלט אחר, אבל זה יכול לגרום לפעולות מסוימות (כגון עריכות עם בדיקות MD5) להיכשל.

פרמטרים שיכולים לקחת ערכים מרובים בדרך־כלל נשלחים עם ערכים מופרדים באמצעות תו מקל, למשל param=value1|value2 או param=value1%7Cvalue2. אם הערך צריך להכיל את תו המקל, יש להשתמש בתו U+001F (מפריד יחידות, Unit Separator) בתור מפריד וגם הוסיפו לתחילת הערך את התו U+001F, למשל param=%1Fvalue1%1Fvalue2.

מספר סוגי פרמטרים ב־API דורשים הסבר נוסף:

boolean: פרמטרים בוליאניים עובדים כמו תיבות סימון ב־HTML: אם הפרמטר צוין, בלי קשר לערך שלו, הוא יטופל בתור אמת. בשביל ערך שקר, יש להשמיט את הפטרמר לגמרי.
expiry: ערכי תפוגה יכולים להיות יחסיים (למשל 5 months או 2 weeks) או מוחלטים (למשל 2014-09-18T12:34:56Z). כדי שלא תהיה תפוגה, יש להשתמש ב־infinite, indefinite, infinity, או never.
timestamp: חותמי־זמן יכולים להיות כתובים במספר תסדירים, ר' את התיעוד של תסדירי קלט של ספריית Timestamp לפרטים. מומלץ להשתמש בתאריך ושעה לפי ISO 8601, כך: 2001-01-15T14:56:00Z. בנוסף, המחרוזת now יכולה לשמש לציון חותם־הזמן הנוכחי.

פרמטרים בתבניות

התכונה "פרמטרים בתבניות" תומכת במקרים שבהם מודול של API זקוק לערך כלשהו עבור ערכים של פרמטרים אחרים. למשל, אם היה מודול API לבקשת פרי, ייתכן שהוא היה זקוק לפרמטר בשם פירות על־מנת לציין מהם הפירות המבוקשים, ולפרמטר בתבנית בשם {פרי}-כמות על־מנת לציין את הכמות של כל פרי עבור הבקשה. לשם כך, לקוח API שמעוניין לקבל תפוח אחד, 5 בננות ו־20 תותים יכול היה ליצור בקשה בסגנון פירות=תפוחים|בננות|תותים&תפוחים-כמות=1&בננות-כמות=5&תותים-כמות=20.

קרדיטים

מפתחי ה־API:

רואן קטאו (מפתח מוביל 2007–2009)
ויקטור וסילייב
בריאן טונג מין
סאם ריד
יורי אסטרחן (יוצר, מפתח מוביל מספטמבר 2006 עד ספטמבר 2007)
בראד יורש (מפתח מוביל מאז 2013)

אנא שלחו הערות, הצעות ושאלות לכתובת mediawiki-api@lists.wikimedia.org או כתבו דיווח באג באתר https://phabricator.wikimedia.org.

אוחזר מתוך "http://wiki.voipe.co.il/index.php/מיוחד:עזרת_API"