Manuel:CORS/fr

L'API MediaWiki supporte les requêtes CORS (cross-origin resource sharing) (en) si $wgCrossSiteAJAXdomains est activé. 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.

Cette page détaille l'utilisation des requêtes CORS dans le code JavaScript pour communiquer entre les wikis de différents domaines.

Description

Page principale : API:Cross-site requests

Pour que les requêtes CORS puissent passer, vous devez fournir un paramètre origin dans la chaîne de la requête avec comme valeur, le protocole et l'hôte du wiki local (par exemple, https://www.mediawiki.org). Cela doit correspondre à l'une des valeurs de $wgCrossSiteAJAXdomains sur le wiki distant.

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.

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ù.

Exemples

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.

Utiliser mediawiki.ForeignApi

Version de MediaWiki :

≥ 1.26

Le module mediawiki.ForeignApi est une extension de mediawiki.api qui gère automatiquement les détails pour vous. Code-level documentation is here.

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!'
} );

Anonymous requests

If the target wiki does not accept cross-origin requests, or if you don't need to perform write actions or read restricted information and want to avoid the overhead, you may set the anonymous option of the mediawiki.ForeignApi constructor:

await mw.loader.using( 'mediawiki.ForeignApi' )
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php', { anonymous: true } );
...

Utiliser les méthodes jQuery

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.

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'
} );

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.

Extensions au mécanisme

CentralAuth

Version de MediaWiki :

≥ 1.26

Page principale : Extension:CentralAuth/API#centralauthtoken

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). This guarantees that the same associated account will be used for actions on both wikis, unlike regular CORS (which requires the user to have previously logged in to the foreign wiki).

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). If you're implementing it yourself, see centralauthtoken for instructions on how to acquire a token (from the local wiki) and pass it to a request (to the foreign wiki).

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). This is simpler but slightly less secure (it fetches and executes arbitrary JavaScript code from the wiki so an attacker who took over the MediaWiki site has an XSS vector against the remote site).