עזרה של MediaWiki API
זהו דף תיעוד של API שנוצר באופן אוטומטי.
תיעוד ודוגמאות: https://www.mediawiki.org/wiki/API
יחידה ראשית
- מקור: MediaWiki
- רישיון: GPL-2.0-or-later
מצב: ה־API של מדיה־ויקי הוא ממשק ותיק ויציב שנתמך ומשתפר באופן סדיר. למרות שאנחנו משתדלים להימנע מכך, לעתים עלינו לבצע שינויים שעלולים לשבש דברים בפונקציונליות הזו; באפשרותך לעשות מינוי לרשימת הדיוור mediawiki-api-announce כדי לקבל הודעות על עדכונים.
בקשות שגויות: כשבקשות שגויות נשלחות ל־API, תישלח כותרת HTTP עם המפתח "MediaWiki-API-Error", ואז גם הערך של הכותרת וגם קוד השגיאה יוגדרו לאותו ערך. למידע נוסף, אפשר לעיין בדף API: שגיאות ואזהרות.
בדיקה: לבדיקה קלה יותר של בקשות, אפשר להשתמש בארגז החול של API.
- action
איזו פעולה לבצע.
- abusefiltercheckmatch
- בדיקה האם מסנן השחתות מתאים לערכת משתנים, לעריכה או לפעולה שנרשמה ביומן ההשחתות.
- abusefilterchecksyntax
- בדיקת תחביר של אחד ממסנני ההשחתות.
- abusefilterevalexpression
- הערכת ביטוי מסנן השחתות.
- abusefilterunblockautopromote
- מסיר ממשתמש את החסימה מפני קבלת קידום אוטומטי כתוצאה מפעולת מסנן השחתות.
- abuselogprivatedetails
- צפייה במידע פרטי של רשומת יומן השחתה.
- block
- חסימת משתמש.
- changeauthenticationdata
- שינוי נתוני אימות עבור המשתמש הנוכחי.
- checktoken
- בדיקת התקינות של האסימון מ־action=query&meta=tokens.
- clearhasmsg
- מנקה את דגל
hasmsg
עבור המשתמש הנוכחי. - clientlogin
- כניסה לוויקי באמצעות זרימה הידודית.
- compare
- קבלת ההבדל בין 2 דפים.
- createaccount
- יצירת חשבון משתמש חדש.
- cspreport
- משמש דפדפנים לדיווח הפרות של מדיניות אבטחת תוכן. המודול הזה לעולם לא ישמש אלא אם הוא משמש עם דפדפן תומך CSP.
- delete
- מחיקת דף.
- edit
- יצירה ועריכה של דפים.
- emailuser
- שליחת דוא"ל למשתמש.
- 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
- לבדוק תקינות ססמה אל מול מדיניות הססמאות של הוויקי.
- watch
- להוסיף דפים לרשימת המעקב של המשתמש הנוכחי או הסרתם ממנה.
- webapp-manifest
- החזרת המניפסט של יישום הרשת.
- tokens
- מיושן. קבלת אסימונים לפעולות שמשנות נתונים.
- אחד מהערכים הבאים: abusefiltercheckmatch, abusefilterchecksyntax, abusefilterevalexpression, abusefilterunblockautopromote, abuselogprivatedetails, block, changeauthenticationdata, checktoken, clearhasmsg, clientlogin, compare, createaccount, cspreport, delete, edit, emailuser, 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, 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 [פתיחה בארגז חול]
סוגי נתונים
קלט למדיה־ויקי צריך להיות בקידוד UTF-8 מנורמל ב־NFC. מדיה־ויקי יכולה לנסות להמיר קלט אחר, אבל זה עלול לגרום לפעולות מסוימות (כגון עריכות עם בדיקות MD5) להיכשל.
חלק מסוגי הפרמטרים בבקשות API דורשים הסבר נוסף:
- בוליאני (boolean)
- פרמטרים בוליאניים עובדים כמו תיבות סימון של HTML: אם הפרמטר צוין, בלי קשר לערך שלו, הוא אמת (true). בשביל ערך שקר (false), יש להשמיט את הפרמטר לגמרי.
- חותם־זמן (timestamp)
- אפשר לכתוב חותמי־זמן במספר תסדירים, ר' את תיעוד תסדירי הקלט של ספריית Timestamp באתר mediawiki.org לפרטים. תאריך ושעה לפי ISO 8601 הוא הדבר המומלץ: 2001-01-15T14:56:00Z. בנוסף, המחרוזת 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.