Manuel:CORS/fr
Cette page détaille l'utilisation des requêtes CORS dans le code JavaScript pour communiquer entre les wikis de différents domaines.
L'API MediaWiki supporte les requêtes CORS (cross-origin resource sharing) (en) si $CrossSiteAJAXdomains est activé.
- authenticated requests if
$wgCrossSiteAJAXdomains
is enabled on the remote wiki.
C'est utile sur les sites Wikimedia, par exemple, pour permettre le téléversement d'images directement sur Commons depuis Wikipédia avec l'interface mobile.
- includes but is not limited to authenticated requests in which a logged in user at the remote wiki performs an action on behalf of the local wiki
- anonymous, non-authenticated requests, used mainly for more limited actions such as fetching publicly available data.
JavaScript methods
Using mediawiki.ForeignApi
MediaWiki's ResourceLoader offers the mediawiki.ForeignApi
module, which is an extension of mediawiki.api
and automatically handles the details for you. It offers two constructors for enabling CORS:
Version de MediaWiki : | ≥ 1.26 |
- For requests to the Action API, use
mw.ForeignApi
.
Version de MediaWiki : | ≥ 1.36 |
- For requests to the REST API, use
mw.ForeignRest
.
Examples are given below. To use mw.ForeignApi
or mw.ForeignRest
, extensions should set mediawiki.ForeignApi
as a ResourceLoader module dependency in extension.json.
If it is necessary for the requested action that the user at the foreign wiki is logged in, pass the assert: 'user'
parameter to get()
/post()
. To assert that the user at the foreign wiki has a specific username, pass the assertuser
parameter with the desired username.
Using Fetch
If the GET request can be made anonymously, you can also use Fetch (the modern, Promise-based replacement for XMLHttpRequest).
Using jQuery.ajax
Si vous ne voulez pas utiliser mediawiki.api pour une raison quelconque, ou si vous êtes intéressé de connaitre son fonctionnement à un niveau plus bas, voici comment implémenter la même fonctionalité en utilisant directement les fonctions AJAX jQuery. Vous pourriez même utiliser directement XMLHttpRequest
.
Examples are given below.
Si vous voulez que le navigateur utilise les cookies qu'il pourrait avoir concernant le domaine, afin de garder l'utilisateur actuel connecté, vous devez aussi initialiser le champ withCredentials
de XMLHttpRequest
à true
.
The origin
parameter
Notez que origin
est une partie de l'URL parce que les requêtes POST de CORS sont préarrangées et que le paramètres de l'origine doit être inclus dans la requête de préarrangement.
- Cela doit correspondre à l'une des valeurs de
$wgCrossSiteAJAXdomains
sur le wiki distant. Note that the value of the origin parameter must begin with the HTTPS protocol (e.g.https://mediawiki.org
), even if$wgCrossSiteAJAXdomains
accepts values without it. - Pour les requêtes anonymes, le paramètre
origin
de la chaîne de requête peut être initialisé à*
ce qui permettra les requêtes de n'importe où.
Examples
Dans les exemples ci-dessous, nous supposons que le wiki local à partir duquel la requête a été émise est www.mediawiki.org
, et que le wiki distant - celui vers lequel la requête est dirigée - est en.wikipedia.org
.
<span id="Using_mw.ForeignApi
">
Utiliser mw.ForeignApi
Authenticated requests
Un exemple qui vérifie si l'utilisateur est connecté sur le wiki distant :
await mw.loader.using( 'mediawiki.ForeignApi' )
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
const data = await api.get( { action: 'query', meta: 'userinfo' } );
alert( `Foreign user ${data.query.userinfo.name} (ID ${data.query.userinfo.id})` );
Un exemple de base d'API d'écriture. Nous demandons un jeton csrf
et l'utilisons pour initialiser une préférence utilisateur persistante qu'un gadget pourra utiliser après cela :
await mw.loader.using( 'mediawiki.ForeignApi' );
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
const data = await api.get( { action: 'query', meta: 'tokens' } );
await api.post( {
action: 'options',
token: data.query.tokens.csrftoken,
optionname: 'userjs-test',
optionvalue: 'Hello world!'
} );
Le même exemple peut être réécrit plus succintement en utilisant quelques méthodes de mediawiki.api helper, qui sont disponibles également pour ForeignApi :
await mw.loader.using( 'mediawiki.ForeignApi' );
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
await api.postWithToken( 'options', {
action: 'options',
optionname: 'userjs-test',
optionvalue: 'Hello world!'
} );
Requêtes anonymes
Si le wiki cible n'accepte pas les requêtes inter-origines, ou si vous n'avez pas besoin de réaliser des actions d'écriture ou de lire des informations restreintes et que vous voulez éviter la surcharge, vous pouvez alors initialiser l'option anonymous
dans le constructeur mediawiki.ForeignApi
:
await mw.loader.using( 'mediawiki.ForeignApi' )
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php', { anonymous: true } );
...
Using mw.ForeignRest
Exemple utilisant l'API REST :
var api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php/v1' );
await api.get( '/page/Main_Page/html' );
An example that queries pages whose page names start with "Test" from Wikimedia Commons (and then logs the results in the browser):
var value = "Test";
var actionApi = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' );
const api = new mw.ForeignRest(
'https://commons.wikimedia.org/w/rest.php/v1',
actionApi,
{ anonymous: true }
);
api.get( '/search/title', {
limit: '10',
q: `${ encodeURIComponent( value ) }`,
origin: '*'
} )
.done( function ( data ) {
console.log( data );
} );
Using Fetch
var apiEndpoint = "https://commons.wikimedia.org/w/api.php";
var params = "action=query&list=allimages&ailimit=3&format=json";
/**
* Send the request to get the images
*/
fetch( apiEndpoint + "?" + params + "&origin=*" )
.then(function(response){
return response.json();
})
.then(function(response) {
var allimages = response.query.allimages; // Process the output to get the image names
Object.keys(allimages).forEach(function(key) {
console.log(allimages[key].name);
});
});
Utiliser les méthodes jQuery
Un exemple qui vérifie si l'utilisateur est connecté sur le wiki distant :
const { query } = await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php',
data: {
action: 'query',
meta: 'userinfo',
format: 'json',
origin: 'https://www.mediawiki.org'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
alert( `Foreign user ${query.userinfo.name} (ID ${query.userinfo.id})` );
Un exemple de base d'API d'écriture :
const { query } = await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php',
data: {
action: 'query',
meta: 'tokens',
format: 'json',
origin: 'https://www.mediawiki.org'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php?origin=https://www.mediawiki.org',
method: 'POST',
data: {
action: 'options',
format: 'json',
token: query.tokens.csrftoken,
optionname: 'userjs-test',
optionvalue: 'Hello world!'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
Extensions au mécanisme
CentralAuth
Version de MediaWiki : | ≥ 1.26 |
CentralAuth permet à votre code d'authentifier sur le wiki distant l'utilisateur actuellement connecté sur le wiki local en utilisant un centralauthtoken. Ceci garanti que le même compte associé sera utilisé pour les actions sur les deux wikis, au contraire d'un CORS régulier (qui nécessite que l'utilisateur se soit auparavent connecté au wiki distant).
Si à la fois le wiki local et le wiki distant ont installé CentralAuth, le mécanisme mediawiki.ForeignApi est étendu de la mème manière pour gérer cela à votre place. Pour l'implémenter vous-même, voir centralauthtoken pour les instructions sur la manière d'acquérir un jeton (du wiki local) et le passer à une requête (au wiki distant).
Autres solutions
Pour les requêtes anonymes vous pouvez utiliser le format JSONP à la place. Ceci est plus simple mais un peu moins sécurisé (il accède et exécute du code JavaScript arbitraire sur le wiki si bien qu'un assaillant qui prendrait la main sur le site MediaWiki aurait un vecteur XSS sur le site distant).