עזרה של MediaWiki API

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

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

יחידה ראשית

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

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

פרמטרים:
action

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

block
חסימת משתמש.
changeauthenticationdata
שינוי נתוני אימות עבור המשתמש הנוכחי.
checktoken
בדיקת התקינות של האסימון מ־action=query&meta=tokens.
clearhasmsg
מנקה את דגל hasmsg עבור המשתמש הנוכחי.
clientlogin
כניסה לוויקי באמצעות זרימה הידודית.
commentblock
באמצעות ה־API‏ "commentblock" ניתן לחסום משתמש מתגובה. יש למלא את הפרמטר CommentID.
commentdelete
באמצעות ה־API‏ "commentdelete" ניתן למחוק תגובה. יש למלא את הפרמטר CommentID.
commentlatestid
באמצעות ה־API‏ "commentlatestID" ניתן לשלוף את המזהה של התגובה האחרונה. יש למלא את הפרמטר pageID.
commentlist
באמצעות ה־API‏ "commentlist" ניתן לשלוף תגובות מרובות ולהציג אותן כרשימה. יש למלא את הפרמטרים הבאים: pageID‏, order‏, pagerPage‏, showForm.
commentsubmit
באמצעות ה־API‏ "commentsubmit" ניתן לשלוח או לפרסם תגובה. יש למלא את הפרמטרים הבאים: pageID‏, parentID‏, commentText.
commentvote
באמצעות ה־API‏ "commentvote" ניתן להצביע על תגובה. יש למלא את הפרמטרים הבאים: commentID‏, voteValue.
compare
קבלת ההבדל בין 2 דפים.
createaccount
יצירת חשבון משתמש חדש.
cspreport
משמש דפדפנים לדיווח הפרות של מדיניות אבטחת תוכן. המודול הזה לעולם לא ישמש אלא אם הוא משמש עם דפדפן תומך CSP.
delete
מחיקת דף.
edit
יצירה ועריכה של דפים.
emailuser
שליחת דוא"ל למשתמש.
embedvideo
⧼apihelp-embedvideo-summary⧽
expandtemplates
הרחבת כל התבניות בתוך קוד הוויקי.
feedcontributions
להחזיר הזנת תרומות משתמש.
feedrecentchanges
להחזיר הזנת שינויים אחרונים.
feedwatchlist
החזרת הזנת רשימת מעקב.
filerevert
לשחזר את הקובץ לגרסה ישנה יותר.
help
הצגת עזרה עבור היחידות שצוינו.
imagerotate
סיבוב של תמונה אחת או יותר.
import
לייבא דף מוויקי אחר או מקובץ XML.
linkaccount
קישור חשבון של ספק צד־שלישי למשתמש הנוכחי.
login
להיכנס ולקבל עוגיות אימות.
logout
יציאה וניקוי של נתוני הפעילות.
managetags
ביצוע פעולות ניהוליות הקשורות בשינוי תגיות.
mergehistory
מיזוג גרסאות של דפים.
mobileview
החזרת נתונים שנחוצים לצפיות ניידות.
move
העברת עמוד.
opensearch
חיפוש בוויקי בפרוטוקול OpenSearch.
options
שינוי העדפות של המשתמש הנוכחי.
paraminfo
קבלת מידע על יחידות של API.
parse
מפענח את התוכן ומחזיר פלט מפענח.
patrol
לנטר דף או גרסה.
protect
לשנות את רמת ההגנה של דף.
purge
ניקוי המטמון לכותרות שניתנו.
query
אחזור נתונים ממדיה־ויקי ועליה.
removeauthenticationdata
הסרת נתוני אימות עבור המשתמש הנוכחי.
resetpassword
שליחת דוא"ל איפוס סיסמה למשתמש.
revisiondelete
מחיקה ושחזור ממחיקה של גרסאות.
rollback
ביטול העריכה האחרונה לדף.
rsd
יצוא סכמת RSD‏ (Really Simple Discovery).
setnotificationtimestamp
עדכון חותם־הזמן של ההודעה עבור דפים במעקב.
setpagelanguage
שינוי השפה של דף.
stashedit
הכנת עריכה במטמון משותף.
tag
הוספת או הסרה של תגים מגרסאות בודדות או עיולי יומן בודדים.
unblock
שחרור משתמש מחסימה.
undelete
שחזור גרסאות של דף מחוק.
unlinkaccount
ביטול קישור של חשבון צד־שלישי מהמשתמש הנוכחי.
upload
העלאת קובץ, או קבלת מצב ההעלאות הממתינות.
userrights
שינוי חברות בקבוצות של המשתמש.
validatepassword
לבדוק תקינות ססמה אל מול מדיניות הססמאות של הוויקי.
visualeditor
החזרת HTML5 עבור דף מתוך שירות פרסואיד.
visualeditoredit
שמירת דף HTML5 למדיה־ויקי (מומר לקוד ויקי דרך שירות פרסואיד).
watch
להוסיף דפים לרשימת המעקב של המשתמש הנוכחי או הסרתם ממנה.
webapp-manifest
החזרת המניפסט של יישום הרשת.
tokens
מיושן. קבלת אסימונים לפעולות שמשנות נתונים.
אחד מהערכים הבאים: block, changeauthenticationdata, checktoken, clearhasmsg, clientlogin, commentblock, commentdelete, commentlatestid, commentlist, commentsubmit, commentvote, compare, createaccount, cspreport, delete, edit, emailuser, embedvideo, expandtemplates, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, help, imagerotate, import, linkaccount, login, logout, managetags, mergehistory, mobileview, move, opensearch, options, paraminfo, parse, patrol, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setnotificationtimestamp, setpagelanguage, stashedit, tag, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, visualeditor, visualeditoredit, watch, webapp-manifest, tokens
ברירת מחדל: 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

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

סוג: מספר שלם
ברירת מחדל: 0
maxage

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

סוג: מספר שלם
ברירת מחדל: 0
assert

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

אחד מהערכים הבאים: user, bot
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.
אחד מהערכים הבאים: plaintext, wikitext, html, raw, none, bc
ברירת מחדל: 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) להיכשל.

חלק מסוגי הפרמטרים בבקשות API דורשים הסבר נוסף:

בוליאני (boolean)
פרמטרים בוליאניים עובדים כמו תיבות סימון של HTML: אם הפרמטר צוין, בלי קשר לערך שלו, הוא אמת (true). בשביל ערך שקר (false), יש להשמיט את הפרמטר לגמרי.
חותם־זמן (timestamp)
אפשר לכתוב חותמי־זמן במספר תסדירים. תאריך ושעה לפי ISO 8601 הוא הדבר המומלת. כל הזמנים מצוינים ב־ UTC, לא תהיה השפעה לשום אזור זמן שיצוין.
  • תאריך ושעה לפי ISO 8601‏, 2001-01-15T14:56:00Z (לא חובה לכתוב פיסוק ו־Z)
  • תאריך ושעה לפי ISO 8601 עם חלקי שנייה (שלא תהיה להם שום השפעה), 2001-01-15T14:56:00.00001Z (לא חובה לכתוב קווים מפרידים, נקודתיים ו־Z)
  • תסדיר MediaWiki‏, 20010115145600
  • תסדיר מספרי כללי, 2001-01-15 14:56:00 (לאזור זמן אופציונלי של GMT‏, +##, או -## אין השפעה)
  • תסדיר EXIF‏, 2001:01:15 14:56:00
  • תסדיר RFC 2822 (אפשר להשמיט את אזור הזמן), Mon, 15 Jan 2001 14:56:00
  • תסדיר RFC 850 (אפשר להשמיט את אזור הזמן), Monday, 15-Jan-2001 14:56:00
  • תסדיר C ctime‏, Mon Jan 15 14:56:00 2001
  • שניות מאז 1970-01-01T00:00:00Z בתור מספר שלך בין 1 ל־13 (לא כולל 0)
  • המחרוזת now
מפריד ערכים מרובים חלופי
פרמטרים שלוקחים ערכים מרובים בדרך־כלל נשלחים עם הערכים מופרדים באמצעות תו מקל, למשל param=value1|value2 או param=value1%7Cvalue2. אם הערך צריך להכיל את תו המקל, יש להשתמש ב־U+001F (מפריד יחידות) בתור המפריד וגם להוסיף לתחילת הערך U+001F, למשל param=%1Fvalue1%1Fvalue2.

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

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

קרדיטים

מפתחי ה־API:

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

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