واجهة برمجة التطبيقات:تسجيل_الدخول
| هذه الصفحة جزء من توثيق واجهة برمجة تطبيقات ميدياويكي التي تحمل اسم Action. |
ربما تتطلب واجهة برمجة تطبيقات ميدياويكي من تطبيقك أو جهازك العميل تقديم بيانات اعتماد مستخدم مصدّقة وتسجيل الدخول لأغراض (أ) الاستعلام عن معلومات أو تصرفات تعدّل بيانات أو (ب) إجراء استعلامات ضخمة الحجم ينتج عنها طلبات تتخطى الحد الأقصى.
استخدام سبيلين اثنين للتصديق
يوجد سبيلين اثنين للتصديق على واجهة برمجة التطبيقات لتطبيق Action على ميدياويكي: باستخدام action=login أو action=clientlogin.
الطريقة الأولى: action=login
يجب على البوتات والتطبيقات غير التفاعلية استخدام مستهلكي OAuth من الملاك فقط لو كان ذلك متوفرا منذ انه يتمتع بأمان أكبر.
لو كان هذا غير متوافر أو لا ينطبق على الجهاز العميل، يجوز استخدام login مع كلمات مرور البوتات.
توثيق واجهة برمجة التطبيقات
مثال
طلب POST
lgtoken الموجود في الطلب المذكور سالفا يرجع من واجهة برمجة التطبيقات:Tokens
النتيجة
{
"login": {
"lguserid": 21,
"result": "Success",
"lgusername": "William"
}
}
عينة من الكود البرمجي
MediaWiki JS
/*
login.js
MediaWiki API Demos
Demo of `Login` module: Sending request to login
MIT License
*/
var api = new mw.Api();
api.login( 'your_bot_username', 'your_bot_password' ).done( function ( data ) {
console.log( 'You are logged in as ' + data.login.lgusername );
} );
JavaScript
/*
edit.js
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
*/
var request = require( 'request' ).defaults( { jar: true } ),
url = 'https://test.wikipedia.org/w/api.php';
// Step 1: GET request to fetch login token
function getLoginToken() {
var params = {
action: 'query',
meta: 'tokens',
type: 'login',
format: 'json'
};
request.get( { url: url, qs: params }, function ( error, res, body ) {
var data;
if ( error ) {
return;
}
data = JSON.parse( body );
loginRequest( data.query.tokens.logintoken );
} );
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( loginToken ) {
var params = {
action: 'login',
lgname: 'bot_username',
lgpassword: 'bot_password',
lgtoken: loginToken,
format: 'json'
};
request.post( { url: url, form: params }, function ( error, res, body ) {
if ( error ) {
return;
}
console.log( body );
} );
}
// Start From Step 1
getLoginToken();
PHP
<?php
/*
login.php
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "/tmp/cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "/tmp/cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "your_bot_username",
"lgpassword" => "your_bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "/tmp/cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "/tmp/cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo( $output );
}
Python
#!/usr/bin/python3
"""
login.py
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
"""
import requests
USERNAME = "your_bot_username"
PASSWORD = "your_bot_password"
S = requests.Session()
URL = "https://www.mediawiki.org/w/api.php"
# Retrieve login token first
PARAMS_0 = {
'action':"query",
'meta':"tokens",
'type':"login",
'format':"json"
}
R = S.get(url=URL, params=PARAMS_0)
DATA = R.json()
LOGIN_TOKEN = DATA['query']['tokens']['logintoken']
print(LOGIN_TOKEN)
# Send a post request to login. Using the main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_1 = {
'action': "login",
'lgname': USERNAME,
'lgpassword': PASSWORD,
'lgtoken': LOGIN_TOKEN,
'format': "json"
}
R = S.post(URL, data=PARAMS_1)
DATA = R.json()
print(DATA)
assert DATA['login']['result'] == 'Success'
بدءًا من إصدار ميدياويكي 1.27، لم يعد مدعومًا استخدام الحساب الرئيسي لتسجيل الدخول. أحصل على بيانات الاعتماد مستخدمًا Special:BotPasswords أو استخدم طريقة
clientlogin. يتطلب تسجيل الدخول وأن تظل مسجلًا الدخول التعامل الصحيح من ملفات تعريف ارتباط إتش تي تي بي على يد جهازك العميل فيما يخص كافة الطلبات. في المثال سالف الذكر، نبين كيف يساعد عنصر الجلسة requests.Session() في إبقاء ملفات تعريف الارتباط.
الأخطاء المحتملة
| الكود | معلومات |
|---|---|
| Failed | اسم مستخدم أو كلمة مرور خطأ. يرجى المحاولة مرة أخرى. |
| Failed | لا يمكن مواصلة تسجيل الدخول. يغلب الظن أن جلستك قد انتهى زمنها. (أو أنك لست تتعامل مع ملفات تعريف الارتباط كما ينبغي). |
| WrongToken | الرمز المقدم غير صالح |
| NeedToken | رمز `lgtoken` لم يقدم |
| Aborted | تسجيل الدخول مستخدما كلمة مرور الحساب الرئيسي بدلا من كلمات مرور البوتات |
| mustpostparams | تم العثور على الوسيط في سلسلة الاستعلام، ولكن يجب أن يكون في نص POST: $1. |
الطريقة الثانية: action=clientlogin
يجب أن تستخدم التطبيقات التفاعلية من قبيل المحررات المخصصة أو تطبيقات المراجعة التي تقدم خدمة ليس الغرض منها أن تكون بديلا كاملا عن الموقع الشبكي أو تطبيقات الأجهزة المحمولة التي تستهدف أن تحل بالكامل محل الوصول إلى واجهة المستخدم عبر الوب تصرف clientlogin.
إلا أن على المرء أن يفضل استخدام OAuth لو كان متوفرًا لأغراض تصديق الأداة ذاتها، منذ أنه أيسر في الاستخدام وآمن كذلك.
هذه الوحدة البرمجية متوفرة منذ إصدار ميدياويكي 1.27.
توثيق واجهة برمجة التطبيقات
مثال 21: عملية لموقع ويكي لا يحتوي على امتدادات تصديق خاصة
طلب POST
api.php?
الحصول على رمز تسجيل الدخول في الطلب سالف الذكر مستخدمًا واجهة برمجة التطبيقات:Tokens.
النتيجة
{
"clientlogin":{
"status":"PASS",
"username":"William"
}
}
عينة من الكود البرمجي
| clientlogin.py |
|---|
#!/usr/bin/python3
"""
clientlogin.py
MediaWiki Action API Code Samples
Demo of `clientlogin` module: Sending post request to login
This demo app uses Flask (a Python web development framework).
MIT license
"""
import requests
from flask import Flask, render_template, flash, request
S = requests.Session()
URL = "https://en.wikipedia.org/w/api.php"
# App config.
DEBUG = True
APP = Flask(__name__)
APP.config.from_object(__name__)
APP.config['SECRET_KEY'] = 'enter_your_secret_key'
@APP.route("/", methods=['GET', 'POST'])
def show_form():
""" Render form template and handle form submission request """
if request.method == 'POST':
username = request.form['username']
password = request.form['password']
start_client_login(username, password)
return render_template('clientlogin_form.html')
def start_client_login(username, password):
""" Send a post request along with login token, user information
and return URL to the API to log in on a wiki """
login_token = fetch_login_token()
response = S.post(url=URL, data={
'action': "clientlogin",
'username': username,
'password': password,
'loginreturnurl': 'http://127.0.0.1:5000/',
'logintoken': login_token,
'format': "json"
})
data = response.json()
if data['clientlogin']['status'] == 'PASS':
flash('Login success! Welcome, ' + data['clientlogin']['username'] + '!')
else:
flash('Oops! Something went wrong -- ' + data['clientlogin']['messagecode'])
def fetch_login_token():
""" Fetch login token via `tokens` module """
response = S.get(
url=URL,
params={
'action': "query",
'meta': "tokens",
'type': "login",
'format': "json"})
data = response.json()
return data['query']['tokens']['logintoken']
if __name__ == "__main__":
APP.run()
|
| form.html |
|---|
<!DOCTYPE html>
<title>MediaWiki Log in</title>
<link rel="stylesheet" href="static/bootstrap/css/bootstrap.min.css">
<div class="container">
<h2>MediaWiki Log in</h2>
<form action="" method="post" role="form">
<div class="form-group">
<div class="form-field">
<div class="label-field">Username</div>
<input name="username">
</div>
<div class="form-field">
<div class="label-field">Password</div>
<input type="password" name="password">
</div>
</div>
<button type="submit" class="btn btn-success">Log in</button>
</form>
<br>
{% with messages = get_flashed_messages(with_categories=true) %}
{% if messages %}
{% for message in messages %}
<div class="alert alert-info">
{{ message[1] }}
</div>
{% endfor %}
{% endif %}
{% endwith %}
</div>
<br>
</div>
</div>
|
مثال 22: عملية لموقع ويكي يحتوي على امتدادات تصديق خاصة
قد يكون الأمر لموقع ويكي يحتوي على امتدادات تصديق خاصة مثل تأكيد التعديل (كابتشا) أو OpenID Connect أو OATHAuth (التصديق باستخدام عنصرين اثنين) عملية تصديق أكثر تعقيدًا. كما قد يتطلب الأمر خانات محددة في تلك الحالة، ويمكن استجلاب بيان هذه من استعلام API:Authmanagerinfo.
الخطوة الأولى: الإجابة على Captcha واختيار تصديق OpenID
أعمال التوثيق هذه مثال لا غير ولا تعرض سلوك أية امتدادات OpenID محددة متاحة حاليًا.
نتوقع من الجهاز العميل إعادة توجيه متصفح المستخدم إلى صفحة
redirecttarget المحددة. سيتولى مقدم خدمة OpenID التصديق ومن ثم إعادة التوجيه إلى صفحة Special:OpenIDConnectReturn على موقع الويكي، التي سوف تتولى التثبت من رد OpenID ومن ثم إعادة التوجيه إلى loginreturnurl شريطة أن تضاف المتغيرات code و state إلى طلب POST الأول المقدم إلى واجهة برمجة التطبيقات. ستنتقل السيطرة على العملية إلى جهاز العميل مرة أخرى عند هذه الخطوة ومن ثم يرسل طلب واجهة برمجة التطبيقات التالي.| الرد |
|---|
{
"clientlogin": {
"status": "REDIRECT",
"redirecttarget": "https://openid.example.net/openid-auth.php?scope=openid&response_type=code&client_id=ABC&redirect_uri=https://wiki.example.org/wiki/Special:OpenIDConnectReturn&state=XYZ123",
"requests": [
{
"id": "OpenIdConnectResponseAuthenticationRequest",
"metadata": {},
"required": "required",
"provider": "OpenID Connect at example.net",
"account": "",
"fields": {
"code": {
"type": "string",
"label": "OpenID Code",
"help": "OpenID Connect code response"
},
"state": {
"type": "string",
"label": "OpenID State",
"help": "OpenID Connect state response"
},
}
}
]
}
}
|
الخطوة الثانية: العودة من OpenID
الآن يحتاج الجهاز العميل أن يطلب من المستخدم التحقق من تطبيق التصديق باستخدام عنصرين اثنين بحثًا عن الكود الحالي ومن ثم تمريره مرة أخرى إلى الخادوم من أجل مواصلة عملية التصديق.
| الرد |
|---|
{
"clientlogin": {
"status": "UI",
"message": "Two-factor authentication",
"requests": [
{
"id": "TwoFactorAuthenticationRequest",
"metadata": {},
"required": "required",
"provider": "",
"account": "",
"fields": {
"code": {
"type": "string",
"label": "Code",
"help": "Two-factor authentication code"
}
}
}
]
}
}
|
الخطوة الثالثة: التصديق باستخدام عنصرين اثنين
من الممكن في بعض الحالات المعينة تلقي رد
RESTART، على سبيل المثال لو كان امتداد OpenID Connect لم يكن يحتوي على ربط لحساب OpenID مرتبط بحساب مستخدم محلي. في هذه الحالة يجوز أن يعيد الجهاز العميل تشغيل عملية تسجيل الدخول من بدايتها أو يجوز أن ينتقل إلى إنشاء حساب، في كلتا الحالتين سيمرر المعامل loginpreservestate أو createpreservestate كي يحافظ على بعض الحالة.| الرد |
|---|
{
"clientlogin": {
"status": "PASS",
"username": "Alice"
}
}
|
ملاحظات إضافية
- من الممكن على مواقع الويكي التي تسمح بالتعديل دون تسجيل دخول تعديل واجهة برمجة التطبيقات دون تسجيل الدخول، إلا أننا ننصح بشدة أن تسجل الدخول. فيما يخص مواقع الويكي الخصوصية، يتطلب الأمر تسجيل الدخول كي تستخدم أي من وظائف واجهة برمجة التطبيقات.
- نحبّذ إنشاء حساب مستخدم لتطبيقك. هذا الأمر مهم على وجه التحديد لو كان تطبيقك ينفذ أعمال تعديل مؤتمتة أو يستدعي استفسارات ضخمة أو تتطلب مقدار كبير من المعالجة. بالنظر إلى ذلك، يسهل متابعة التغييرات التي أجراها التطبيق وإسباغ حقوق خاصة للحساب الذي يستخدمه التطبيق.
- لو كنت ترسل طلب يجب أن يرسله مستخدم مسجل الدخول، أضف المتغير
assert=userإلى الطلب الذي ترسله كي تتحقق من أن المستخدم مسجل الدخول أم لا. لو كان المستخدم غير مسجل الدخول، سوف يرد الطلب كود الخطأassertuserfailedإليك. طالع واجهة برمجة التطبيقات:أكّد لترى التفاصيل. - لو كنت تريد أن تتحقق من أن حساب ما يتمتع بحقوق بوت، أضف المتغير
assert=botإلى الطلب. لو كان الحساب لا يتمتع بحقوق بوت، سوف يرد الطلب كود الخطأassertbotfailedإليك. طالع واجهة برمجة التطبيقات:أكّد لترى التفاصيل.
انظر أيضا
- واجهة برمجة التطبيقات:تسجيل_الخروج
- واجهة برمجة التطبيقات:معلومات_مستخدم - يرد معلومات عن المستخدم مسجل الدخول حاليًا
- تسجيل الدخول التفاعلي مستخدمًا action=clientlogin في mwapi