עזרה של 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
איזו פעולה לבצע.
- abusefiltercheckmatch
- בדיקה האם מסנן השחתות מתאים לערכת משתנים, לעריכה או לפעולה שנרשמה ביומן ההשחתות.
- abusefilterchecksyntax
- בדיקת תחביר של אחד ממסנני ההשחתות.
- abusefilterevalexpression
- הערכת ביטוי מסנן השחתות.
- abusefilterunblockautopromote
- מסיר ממשתמש את החסימה מפני קבלת קידום אוטומטי כתוצאה מפעולת מסנן השחתות.
- abuselogprivatedetails
- צפייה במידע פרטי של רשומת יומן השחתה.
- acquiretempusername
- קבלת שם חשבון חולף ואחסונו במאגר של ההתחברות הנוכחית, אם יצירת חשבון חולף מופעלת והמשתמש הנוכחי לא נכנס לחשבון. אם כבר נשמר שם במאגר, מוחזר אותו השם.
- antispoof
- בדיקת שם משתמש אל מול בדיקות נרמול של AntiSpoof.
- block
- חסימת משתמש.
- centralauthtoken
- אחזור centralauthtoken לביצוע בקשה מאומתת לוויקי משויך.
- centralnoticecdncacheupdatebanner
- בקשת ניקוי תוכן של כרזה שמאוחסנת במטמון ה־CDN (צד־לקוח) למשתמשים אלמוניים, עבור הכרזה והשפה המבוקשות
- centralnoticechoicedata
- קבלת נתונים שדרושים לבחירת כרזה למיזם ושפה הנתונים
- centralnoticequerycampaign
- קבלת כל ההגדרות של מבצע הפרסום.
- changeauthenticationdata
- שינוי נתוני אימות עבור המשתמש הנוכחי.
- changecontentmodel
- שינוי מודל התוכן של דף
- checktoken
- בדיקת התקינות של האסימון מ־action=query&meta=tokens.
- cirrus-config-dump
- היטל של הגדרות CirrusSearch.
- cirrus-mapping-dump
- היטל של מיפויי CirrusSearch עבור הוויקי הזה.
- cirrus-profiles-dump
- היטל של פרופילי CirrusSearch עבור הוויקי הזה.
- cirrus-settings-dump
- היטל של הגדרות CirrusSearch עבור הוויקי הזה.
- clearhasmsg
- מנקה את דגל
hasmsgעבור המשתמש הנוכחי. - clientlogin
- כניסה לוויקי באמצעות זרימה הידודית.
- compare
- קבלת ההבדל בין שני דפים.
- createaccount
- יצירת חשבון משתמש חדש.
- createlocalaccount
- יצירת חשבון מקומי בכפייה. החשבון המרכזי חייב להתקיים.
- delete
- מחיקת דף.
- deleteglobalaccount
- מחיקת משתמש גלובלי.
- discussiontoolsedit
- שליחת הודעה בדף שיחה.
- discussiontoolsfindcomment
- מציאת תגובה לפי המזהה או השם שלה.
- discussiontoolsgetsubscriptions
- קבלת מצב המעקב של הנושאים הנתונים.
- discussiontoolssubscribe
- להירשם (או לבטל רישום) לקבלת התראות על נושא
- discussiontoolsthank
- לשלוח התראה על הודעת תודה פומבית על תגובה.
- echocreateevent
- גרימה ידנית לשליחת התראה למשתמש
- echomarkread
- סימון שההודעות נקראו עבור המשתמש הנוכחי.
- echomarkseen
- סימון שההודעות נצפו עבור המשתמש הנוכחי.
- echomute
- השתקה או הפעלה של התראות ממשתמשים או מדפים מסוימים.
- edit
- יצירה ועריכה של דפים.
- editmassmessagelist
- עריכה של רשימת מסירה המונית.
- emailuser
- שליחת דוא"ל למשתמש.
- expandtemplates
- פורס את כל התבניות בתוך קוד הוויקי.
- featuredfeed
- החזרת הזנת תוכן מומלץ.
- feedcontributions
- מחזיר הזנת תרומות משתמש.
- feedrecentchanges
- מחזיר הזנת שינויים אחרונים.
- feedwatchlist
- מחזיר הזנת רשימת מעקב.
- filerevert
- שחזור קובץ לגרסה ישנה יותר.
- globalblock
- חסימה גלובלית או שחרור חסימה גלובלית של משתמש.
- globalpreferenceoverrides
- שינוי החריגות המקומיות של ההעדפות הגלובליות עבור המשתמש הנוכחי.
- globalpreferences
- שינוי ההעדפות הגלובליות של המשתמש הנוכחי.
- globaluserrights
- הוספה/הסרה של משתמש אל/מתוך קבוצות גלובליות.
- help
- הצגת עזרה עבור היחידות שצוינו.
- imagerotate
- המודול הזאת כובה.
- import
- יבוא דף מוויקי אחר או מקובץ XML.
- jsonconfig
- אפשרות לגישה ישירה לתת־מערכת של JsonConfig.
- languagesearch
- חיפוש של שמות שפות בכל שיטת כתב.
- linkaccount
- קישור חשבון של ספק צד־שלישי למשתמש הנוכחי.
- login
- כניסה וקבלת עוגיות אימות.
- logout
- יציאה וניקוי של נתוני ההתחברות.
- managetags
- ביצוע פעולות ניהוליות הקשורות בתגי שינוי.
- massmessage
- שליחת הודעה לרשימת דפים.
- mergehistory
- מיזוג גרסאות של דפים.
- move
- העברת דף.
- opensearch
- חיפוש בוויקי בפרוטוקול OpenSearch.
- options
- שינוי העדפות של המשתמש הנוכחי.
- paraminfo
- קבלת מידע על יחידות של API.
- parse
- מפענח את התוכן ומחזיר פלט מפענח.
- patrol
- לנטר דף או גרסה.
- protect
- לשנות את רמת ההגנה של דף.
- purge
- ניקוי המטמון לכותרות שניתנו.
- query
- אחזור נתונים ממדיה־ויקי ועליה.
- removeauthenticationdata
- הסרת נתוני אימות עבור המשתמש הנוכחי.
- resetpassword
- שליחת דוא"ל איפוס סיסמה למשתמש.
- revisiondelete
- מחיקה ושחזור ממחיקה של גרסאות.
- rollback
- ביטול העריכה האחרונה לדף.
- rsd
- יצוא סכמת RSD (Really Simple Discovery).
- setglobalaccountstatus
- הסתרה או נעילה (או ביטול הסתרה או ביטול נעילה) של חשבון משתמש גלובלי.
- setnotificationtimestamp
- עדכון חותם־הזמן של ההודעה עבור דפים במעקב.
- setpagelanguage
- שינוי השפה של דף.
- shortenurl
- קיצור כתובת URL ארוכה.
- sitematrix
- קבלת רשימת אתרי ויקימדיה.
- spamblacklist
- בדיקת תקינות של URL אחד או יותר אל מול רשימת חסימת הספאם.
- streamconfigs
- חשיפת הגדרות זרם אירועים. מחזיר רק format=json עם formatversion=2.
- strikevote
- מתן אפשרות למפעילי מערכת למחוק קול או לבטל את מחיקתו.
- tag
- הוספה או הסרה של תגים מגרסאות בודדות או רשומות יומן בודדות.
- templatedata
- אחזור נתונים שמאוחסנים בהרחבה TemplateData.
- thank
- שליחת התראת תודה לעורך.
- titleblacklist
- בדיקת תקינות של כותרת דף, שם קובץ, או שם משתמש אל מול TitleBlacklist.
- torblock
- בדיקה אם כתובת IP חסומה בתור צומת יציאה של Tor.
- transcodereset
- משתמשים עם ההרשאה "transcode-reset" יכולים לאתחל ולהריץ מחדש משימת המרה משנית.
- unblock
- שחרור חסימת משתמש.
- undelete
- שחזור גרסאות של דף מחוק.
- unlinkaccount
- ביטול קישור של חשבון צד־שלישי מהמשתמש הנוכחי.
- upload
- העלאת קובץ, או קבלת מצב ההעלאות הממתינות.
- userrights
- שינוי חברות בקבוצות של המשתמש.
- validatepassword
- לבדוק תקינות סיסמה אל מול מדיניות הסיסמאות של הוויקי.
- watch
- להוסיף דפים לרשימת המעקב של המשתמש הנוכחי או להסיר אותם ממנה.
- webapp-manifest
- החזרת המניפסט של יישום הרשת.
- webauthn
- מודול API לתקשורת בין השרת ללקוח בעת תהליך רישום/אימות.
- bouncehandler
- פנימי. קבלת דוא"ל קופץ ועיבודו כדי לטפל במקבל כושל.
- categorytree
- פנימי. מודול פנימי של ההרחבה CategoryTree.
- cirrus-check-sanity
- פנימי. דיווח על על הנכונות של טווח מזהי דף במפתח החיפוש
- collection
- פנימי. מודול API לביצוע פעולות מגוונות על אוסף של משתמש ויקי.
- cspreport
- פנימי. משמש דפדפנים לדיווח הפרות של מדיניות אבטחת תוכן. המודול הזה לעולם לא ישמש אלא אם הוא משמש עם דפדפן תומך CSP.
- discussiontoolscompare
- פנימי. קבלת מידע על שינויי תגובות בין שתי גרסאות דף.
- discussiontoolspageinfo
- פנימי. מחזירה מטא־נתונים דרושים כדי לאתחל את כלי השיחה.
- discussiontoolspreview
- פנימי. תצוגה מקדימה של הודעה בדף שיחה.
- editcheckreferenceurl
- פנימי. Check the status of a URL for use as a reference.
- fancycaptchareload
- פנימי. קבלת FancyCaptcha חדשה.
- jsondata
- פנימי. אחזור נתוני JSON המותאמים למקום.
- oathvalidate
- פנימי. בדיקת תקינות של אסימון אימות דו־שלבי (OATH).
- parser-migration
- פנימי. פענוח דף עם שתי תצורות שונות של המפענח.
- readinglists
- פנימי. פעולות כתיבה ברשימות קריאה.
- sanitize-mapdata
- פנימי. ביצוע בדיקת תקינות נתונים עבור ההרחבה Kartographer
- scribunto-console
- פנימי. יחידה פנימית להבאת בקשות XHR ממסוף Scribunto.
- securepollauth
- פנימי. מאפשרת לוויקי מרוחק לאמת משתמשים לפני מתן זכות להצביע בבחירות.
- stashedit
- פנימי. הכנת עריכה במטמון משותף.
- timedtext
- פנימי. מספק תוכן טקסט מתוזמן לשימוש ברכיבי <track>
- ulslocalization
- פנימי. קבלת תרגומי ממשק של בורר השפות האוניברסלי בשפה הנתונה.
- ulssetlang
- פנימי. לעדכן את שפת הממשק המועדפת של המשתמש.
- visualeditor
- פנימי. החזרת HTML5 עבור דף מתוך שירות פרסואיד.
- visualeditoredit
- פנימי. שמירת דף HTML5 למדיה־ויקי (מומר לקוד ויקי דרך שירות פרסואיד).
- wikimediaeventsblockededit
- פנימי. רישום מידע על ניסיונות עריכה בזמן חסימה
- אחד מהערכים הבאים: abusefiltercheckmatch, abusefilterchecksyntax, abusefilterevalexpression, abusefilterunblockautopromote, abuselogprivatedetails, acquiretempusername, antispoof, block, centralauthtoken, centralnoticecdncacheupdatebanner, centralnoticechoicedata, centralnoticequerycampaign, changeauthenticationdata, changecontentmodel, checktoken, cirrus-config-dump, cirrus-mapping-dump, cirrus-profiles-dump, cirrus-settings-dump, clearhasmsg, clientlogin, compare, createaccount, createlocalaccount, delete, deleteglobalaccount, discussiontoolsedit, discussiontoolsfindcomment, discussiontoolsgetsubscriptions, discussiontoolssubscribe, discussiontoolsthank, echocreateevent, echomarkread, echomarkseen, echomute, edit, editmassmessagelist, emailuser, expandtemplates, featuredfeed, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, globalblock, globalpreferenceoverrides, globalpreferences, globaluserrights, help, imagerotate, import, jsonconfig, languagesearch, linkaccount, login, logout, managetags, massmessage, mergehistory, move, opensearch, options, paraminfo, parse, patrol, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setglobalaccountstatus, setnotificationtimestamp, setpagelanguage, shortenurl, sitematrix, spamblacklist, streamconfigs, strikevote, tag, templatedata, thank, titleblacklist, torblock, transcodereset, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, watch, webapp-manifest, webauthn, bouncehandler, categorytree, cirrus-check-sanity, collection, cspreport, discussiontoolscompare, discussiontoolspageinfo, discussiontoolspreview, editcheckreferenceurl, fancycaptchareload, jsondata, oathvalidate, parser-migration, readinglists, sanitize-mapdata, scribunto-console, securepollauth, stashedit, timedtext, ulslocalization, ulssetlang, visualeditor, visualeditoredit, wikimediaeventsblockededit
- ברירת המחדל: 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.
- ברירת המחדל: 0
- maxage
להגדיר את כותר
max-ageלבקרת מטמון HTTP למספר כזה של שניות. שגיאות אף פעם לא מוטמנות.- סוג: מספר שלם
- הערך לא יכול להיות קטן מ־0.
- ברירת המחדל: 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
- variant
הגוון השפה. עובד רק אם השפה הבסיסית תומכת בהמרה בין הגוונים.
- 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
אם ניתן, הטקסטים של השגיאות ישתמשו בהודעות מותאמות מקומית ממרחב השם מדיה ויקי.
- סוג: בוליאני (פרטים)
- centralauthtoken
בעת גישה לבקשת AJAX חוצה־תחומים (CORS), יש להשתמש בזה כדי להתאמת בתור משתמש SUL נוכחי. יש להשתמש ב־action=centralauthtoken באתר הוויקי הזה כדי לאחזר את האסימון לפי ביצוע בקשת CORS. בכל אסימון אפשר להשתמש רק פעם אחת, והוא פג אחרי 10 שניות. זה אמור להיכלל בכל בקשה לפני טיסה ולכן זה צריך להיות כלול ב־URI של הבקשה (לא בגוף ה־POST).
- עזרה ליחידה הראשית.
- api.php?action=help [פתיחה בארגז חול]
- כל העזרה בדף אחד.
- api.php?action=help&recursivesubmodules=1 [פתיחה בארגז חול]
סוגי נתונים
קלט למדיה־ויקי אמור להיות 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:
- יורי אסטרחן (יוצר, מפתח מוביל מספטמבר 2006 עד ספטמבר 2007)
- רואן קטאו (מפתח מוביל מספטמבר 2007 עד 2009)
- ויקטור וסילייב
- בריאן טונג מין
- סאם ריד
- בראד יורש (מפתח מוביל מ־2013 עד 2020)
נא לשלוח הערות, הצעות ושאלות לכתובת mediawiki-api@lists.wikimedia.org או כתבו דיווח באג באתר https://phabricator.wikimedia.org.