API:メイン ページ

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Main page and the translation is 100% complete.

Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Esperanto • ‎Nederlands • ‎Taqbaylit • ‎Tiếng Việt • ‎Türkçe • ‎azərbaycanca • ‎dansk • ‎español • ‎français • ‎italiano • ‎lietuvių • ‎occitan • ‎polski • ‎português • ‎português do Brasil • ‎română • ‎čeština • ‎български • ‎русский • ‎українська • ‎հայերեն • ‎العربية • ‎سنڌي • ‎فارسی • ‎پښتو • ‎मराठी • ‎मैथिली • ‎हिन्दी • ‎বাংলা • ‎ಕನ್ನಡ • ‎ไทย • ‎中文 • ‎文言 • ‎日本語 • ‎粵語 • ‎한국어
このページでは、「操作」API の概要を記述します。 下位トピックや他の API の詳細は、右のメニュー バーを参照してください。

MediaWiki 操作 API は、ウィキの機能、データ、メタデータに、通常は api.phpManual:api.php にある URL 経由で、HTTP でアクセスする便利な手段を提供するウェブ サービスです。 クライアントがaction パラメータを指定して特定の「アクション」を要求したときは、おもに action=query によって情報を得ます。 通称は究極の MediaWiki API でしたが、今では MediaWiki に接続するその他のウェブ API MediaWiki があります。たとえば REST APIウィキデータ・クエリサービスもその一部です。

はじめに

「内部 API」や「PHP API」をお探しの場合は、PHP 開発者が MediaWiki インストレーションに新しい機能を追加できるようにする拡張機能のインターフェイスをご覧ください。
廃止の告知は流量の少ない mediawiki-api-announce メーリングリストに配信されます。 購読をお勧めします。

MediaWiki の操作 API は、MediaWiki のインストレーションを監視したり、自動で保守するボットの作成に使用できます。 ウェブ API は、MediaWiki のデータベース内のデータへの直接的で高水準なアクセス手段を提供します。 クライアント プログラムは、ウェブ サービスに対して HTTP リクエストを送信することで、ウィキへのログイン、データ取得、変更内容の投稿という処理を自動的に実行できます。 対応しているクライアントにはウェブベースの軽量な JavaScript クライアントとしてbots(ボット)やナビゲーション・ポップアップなどの他、LiveRCVandal Fighter などエンド ユーザー アプリケーションや、その他のウェブ サイト (Toolforgeのユーティリティ) などがあります。

MediaWiki の新しいインストレーションでは、ウェブ サービスは既定で有効になっていますが、管理者が無効にできます。

MediaWiki には外部向けのインターフェイスが他に 2 つあります:

単純な例

この URL は、英語版ウィキペディアのウェブ サービス API に、メインページの本文を送信させます:

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=json&formatversion=2

HTTP GET リクエストを送信するために、あらゆるプログラミング言語を使用できます (単にブラウザーでリンクにアクセスするだけでも構いません)。すると、「Main Page」という名前のページの現在のウィキ マークアップを含む JSON 文書が得られます。 形式を jsonfm に変更することで、「pretty-printed」(読みやすく整形された) HTML が得られます。これはデバッグに役立ちます。

ここで読みやすいクリッカブルなリンクとして、特定のjsonfm URLを使って説明します。

URL を分解して機能の仕組みを調べることにします。

エンドポイント

https://en.wikipedia.org/w/api.php

これが「エンドポイント」です。 MediaWiki ウェブ サービス API のホームページのようなものです。 このURLは英語版ウィキペディアのAPIの基本URLで、ちょうどhttps://en.wikipedia.org/wiki/がこのウェブサイトの基本URLであるのと対比できます。

もし英語版ウィキペディアで走るプログラムを作成するなら、構築するURLすべての冒頭は、この基本URLで始まります。 もしそれ以外のMediaWikiインストレーションを使用するなら、まずそのエンドポイントを調べて、それを使用します。ウィキメディアのウィキでは、エンドポイントはそれぞれ以下の形式に従います。

https://www.mediawiki.org/w/api.php     # MediaWiki API
https://en.wikipedia.org/w/api.php      # 英語版ウィキペディアの API
https://nl.wikipedia.org/w/api.php      # オランダ語版ウィキペディアの API
https://commons.wikimedia.org/w/api.php # ウィキメディア・コモンズの API


MediaWiki バージョン: 1.17

r75621以降はエンドポイントにRSDを用いています。ページ内でHTMLソースのlink rel="EditURI"部分を探し、api.php URLを抽出します。実際のリンク先に詳細な説明があります。 例えば、このウィキでは下記の部分が該当します:

<link rel="EditURI" type="application/rsd+xml" href="//www.mediawiki.org/w/api.php?action=rsd" />

これ以外に、どのウィキであってもエンドポイントを安全に見つける方法はありません。 運がいいと、index.phpのフルパスを奇妙な書き換えルールの陰に隠さずに提供してあり、処理は「edit」(あるいは履歴 history)リンクからindex.php (etc.) をapi.phpに書き換えるだけの場合、あるいは既定のscript pathw/api.phpなど)を使えばよい場合などがありえます。

次に注目するのは、URLのクエリ行の変数です。

形式 (format)

format=json APIに対し、データ返り値をJSON形式にするよう指示します。 バグ修正に使うHTML版を入手するなら、format=jsonfmを試用してみましょう。 APIは他にも XMLnative PHP のような出力形式をサポートしていますが、使用頻度の低い形式を廃止する (phab:T95715) ことが計画されており、それらの使用はおすすめできません。

操作 (action)

action=query

MediaWikiウェブサービスAPIは何十種類もの操作を実行でき、拡張機能はさらに多くを実行します。API helpを開くと特定のウィキでどんな操作が使えるか、動的な構造の説明文書に網羅してあります。 この事例では情報を得るために「query」操作を選びました。 「query」つまり照会(クエリ)とはAPIの最も重要な操作で、専用の詳しい説明文書が用意されています。 下記に示す解説は、たった1つの例を説明しています。

操作固有のパラメーター

titles=Main%20Page

上記のURLのサンプルに戻り、「query」操作の変数を見てみましょう。 サンプルではウェブサービスAPIに、求めている情報は「Main Page」というウィキページに関するものだと指示しています。 (%20 は 空白 (スペース) をパーセントエンコーディングしたものです。) 複数のページを照会する場合は、すべてを1件の要求にまとめてネットワークとサーバのリソースを最適化する: titles=PageA|PageB|PageC。 詳細はクエリの説明文書を参照してください。

prop=revisions

単一のページを対象に、多くの情報、つまりproperties(属性)を照会できます。属性という変数はウェブサービスAPIに、ページの特定版から情報を得るように指示します。 特定版について何も情報を与えていないため、APIは最近の更新—ウィキペディアの現状のメインページの情報を返します。

rvprop=content

その結果、この変数によってウェブサービスAPIに対し、そのページの最近の更新の内容を返すように指示します。 もしもrvprop=content|userを与えた場合は、ぺの最近の更新の内容と、さらに直近に編集した利用者の名前を返します。

繰り返しますが、これは一例にすぎません。 クエリ(照会)はこちらで詳しく解説し、the API referenceには可能な操作の他、rvpropに与える全ての値の一覧などをまとめてあります。


さあ、はじめましょう

MediaWiki web service APIを使い始める前に、以下の文書を読んでください,

  • FAQ.
  • 入出力フォーマットについてのページ
  • エラーと警告についてのページ
  • アクセスしようとするウィキに適用されるすべての方針。例えばウィキメディア財団ウィキの利用規約商標の使用方針など。これらの規約はAPIを利用したアクセスや編集を対象とし、ウェブブラウザを使用するときと同等に扱われます。

それ以降に読むべきページは利用者の目的により決まります。画面右手のメニューはタスク単位でまとめた詳しい説明文書のリンク集で、その他の一般的なガイドラインは下記に示してあります。

クライアントを識別する

MediaWikiウェブサービスAPIに対してHTTP依頼をするときは、ご利用のクライアントを正しく識別するUser-Agent接頭辞を必ず明示してください。クライアントのライブラリが提供する既定のUser-Agentを使わず、ご利用のスクリプトまたはサービスを識別する固有の接頭辞を作成し、利用者とのなんらかの連絡手段(例えばメールアドレス)がわかるようにします。

ユーザーエージェントのストリングとして、次のサンプルを提示します:

MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

ウィキメディアのウィキにおいてUser-Agent接頭辞を示さない、あるいは値が空や特定不能の場合は、依頼に対してHTTP 403エラーを返します(m:User-Agent policy参照)。MediaWikiの他のインストレーションでも同様の方針が適用されます。

ブラウザベースのJavaScriptを用いてAPIを呼び出すと、User-Agent接頭辞を励起できません。ブラウザ独自のユーザーエージェントが使われます。回避するにはApi-User-Agent接頭辞を次のように使います:

// Using XMLHttpRequest
xhr.setRequestHeader( 'Api-User-Agent', 'Example/1.0' );

// Using jQuery
$.ajax( {
    url: remoteUrlWithOrigin,
    data: queryData,
    dataType: 'json',
    type: 'POST',
    headers: { 'Api-User-Agent': 'Example/1.0' },
    success: function(data) {
       // do something with data
    }
} );

// Using mw.Api, specify it when creating the mw.Api object
var api = new mw.Api( {
    ajax: {
        headers: { 'Api-User-Agent': 'Example/1.0' }
    }
} );
api.get( {...} ).done(function(data) {
    // do something with data
});

// Using fetch
fetch( remoteUrlWithOrigin, {
    method: 'POST',
    headers: new Headers( {
        'Api-User-Agent': 'Example/1.0'
    } )
    // Other init settings such as 'credentials'
} ).then( function ( response ) {
    if ( response.ok ) {
        return response.json();
    }
    throw new Error( 'Network response was not ok: ' + response.statusText );
} ).then( function ( data ) {
    // do something with data
});

PHPでユーザーエージェントを宣言するには次の例のコードを使います:

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');

cURLをご利用の場合は:

curl_setopt($curl, CURLOPT_USERAGENT, 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');

ログイン

クライアントはMediaWikiへのログインを求められることがあり、独自の利用者アカウントから入るように指示されるかもしれません。詳細はログインの手続きのページを参照してください。

APIエチケット

API:エチケットも参照してください

もしキャッシュ可能なデータを要求した場合はキャッシュする手順を踏んでください。同じデータを何度も要求しないためです。レート制限や並行性他、一般的なAPIエチケットをAPI:Etiquetteで説明しています。中には独力でデータのキャッシュができるクライアントもいますが、その他(特にJavaScript使用者)には不可能です。

HTTP仕様により、POST要求はキャッシュの対象外です。そこでウェブサービスAPIからデータを書き出す場合は必ずGET要求を使うべきで、POSTは使いません。

またURLが完全に一致する場合を除き、キャッシュから要求は実行できない点にも合わせてご留意ください。api.php?....titles=Foo|Bar|Helloを要求して結果をキャッシュすると、api.php?....titles=Hello|Bar|Hello|Fooの要求は — たとえ結果としてMediaWikiからの返し値が同値でも、キャッシュでは処理されません!

You should take care to normalize the URLs you send to the MediaWikiウェブサービスに送るURLは注意して正規化してください。利用者の入力にごく些細な書き間違いがあったせいで不要なHTTP依頼が発生し、時間を無駄にすることを予防するためです。ページ名の一覧を正規化するには、重複する項目の削除ページ名のABC順並べ替えが有効です。種類の異なるデータにも同様の処理が応用できます。

便利なリンク

このページの画面右側のメニューバー(PC版表示)から、タスク単位でまとめた詳しい説明文書にリンクしています。API全体に関わるリンクの一部を次に示します:

アーカイブリンク

  • 2006 API discussion —2006年ウィキマニアカンファレンスで行われたAPIの協議