Jump to content

API:チュートリアル

From mediawiki.org
This page is a translated version of the page API:Tutorial and the translation is 31% complete.
Languages:

このチュートリアルではMediaWiki 操作 APIについて使い方、申請の書式、簡単なクエリの実行、またこの API を 活用するプロジェクトの一覧が載せてあります。

Toolforge で見本用のアプリを探す

MediaWiki操作APIの概要

MediaWiki 操作 API とは RESTのある ウェブサービスで利用者にページ作成や検証あるいは構文解析など、特定のウィキ操作を実行できるようにします。 API:メインページ はこのアプリを理解する糸口として適しています。

皆さんのプログラムから API に対して、ウィキ機能を使う許可を申し入れます。 たとえばウィキにログインしたり 新規ページの作成や編集、記事の題名を検索し、コンテンツの文章を検索し、またはコンテンツの構文解析を実行します。 操作 API の使用は第三者の開発者やウィキメディアの拡張機能開発者、ウィキサイトの管理者が対象です。

On the right sidebar of this page, there are many features that are supported by the API, grouped by category. Before sending requests to a wiki server, first read through the overview pages such as data formats, errors and warnings, and the Action API FAQ.

MediaWiki操作APIの使い方

You can request for data from client side to the server over HTTP and get the response back in a standard format (typically JSON). A request consists of an endpoint and a set of parameters. There are two types of request that can be made: GET and POST. For a GET request, a parameter would contain a query string in the URL. For a POST request, format the parameters in JSON format.

リクエストの書式

All Wikimedia Wikis have endpoints in this format http://example.org/w/api.php. To operate on the MediaWiki main site or English Wikipedia, use the related endpoint. For example, the English Wikipedia is at https://en.wikipedia.org/w/api.php. For testing new accounts or test edits to pages, use the test wiki endpoint https://test.wikipedia.org/w/api.php.

In the query string in the URL, add the action parameter. It tells the API which action to perform. The most popular action is query (the URL would contain action=query), which allows fetching data from a wiki. Following the action parameter, add another parameter to indicate which one of the three query module types you want to perform:

  • prop - get properties of pages  
  • list - get list of pages matching a certain criterion
  • meta - get meta information about the wiki and user

Finally, include the format parameter, which tells the API in which format to get the results. The recommended format is JSON. The API has supported other output formats in the past, but they are not generally recommended.

Request format
Request format

単純なクエリ

Let’s take an example of a simple query to understand what a typical GET request and response would look like in the context of the Action API.

Let's search for a title in a wiki. We will use the search module documented on API:検索 .

GET リクエスト

To search for page titles or content matching Craig Noone, the URL for the HTTP GET request would be:

api.php?action=query&list=search&srsearch=Craig%20Noone&format=json [ApiSandbox で試用する]

Explanation of each part of the URL:

  • http://en.wikipedia.org/w/api.php is the main endpoint. In this case it is English Wikipedia.
  • action=query means fetch data from wiki.
  • list=search means get list of pages matching a criteria.
  • srsearch=Craig%20Noone indicates the page title or content to search for. The %20 indicates a space character in a URL.
  • format=json indicates JSON output, which is the recommended output format.

レスポンス

The response is a JSON format document with a list of pages titles that match Craig Noone: 

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}


操作APIを利用しているプロジェクトの例

Some example of projects in Wikimedia that use Action API:

  • Wikipedia iOS App, in which one of the features is to search for wiki pages near your location.
  • Bots that operate on a wiki. Pywikibot is a bot framework written in Python that interfaces with MediaWiki API which a lot of bot developers use.
  • API use in visualizing data obtained from a wiki. Such as this neat visualization that shows real time edits made on Wikipedia.

追加的な注記

  • Several sites are using MediaWiki. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
  • If you want to make a lot of API calls, and perhaps run very busy and active bots, talk to wiki admins ahead of time, so they do not block you. See list of Administrators of Wikimedia projects. Read more about this topic on API:エチケット .
  • All data modifying actions such as logging, editing or moving a page, and watching or patrolling changes would require tokens. You would need to obtain tokens via API:トークン to proceed further.

リソース

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Tutorial/ja&oldid=6079905"