API:대문

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page API:Main page and the translation is 51% complete.
Outdated translations are marked like this.
Other languages:
العربية • ‎български • ‎বাংলা • ‎Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎हिन्दी • ‎Հայերեն • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎ಕನ್ನಡ • ‎한국어 • ‎lietuvių • ‎मैथिली • ‎मराठी • ‎Nederlands • ‎occitan • ‎polski • ‎پښتو • ‎português • ‎português do Brasil • ‎română • ‎русский • ‎سنڌي • ‎українська • ‎粵語 • ‎中文
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
This is an overview of the "action" API. See the menu bar on the right for more detailed sub-topics and other APIs.

미디어위키 웹 API는 HTTP를 통해 기능,데이터,메타 데이터로 편리하게 접근할 수 있게 하는 웹 서비스입니다. Clients request particular "actions" by specifying an action parameter, mainly action=query to get information. It was known as the MediaWiki API, but there are now other web APIs available that connect to MediaWiki such as RESTBase and the Wikidata query service.

소개[edit]

Note 주의: "내부 API" 또는 "PHP API"에 관심이 있으시다면, PHP 개발자가 미디어위키에 새로운 기능을 추가할 수 있게 하는 확장 인터페이스를 보세요.

미디어 위키 웹 API는 유지보수를 위해 미디어위키 설치본 모니터링이나 붓을 만드는데 사용됩니다. 미디어위키 데이터베이스에 들어 있는 데이터로의 고수준의, 직접적인 접근을 제공합니다. 클라이언트 프로그램들은 웹 서비스로의 HTTP 요청을 만들어 자동으로 위키에 로그인하고, 데이터를 얻고, 변경 사항을 게시할 수 있습니다. 지원되는 클라이언트들 중에는 붓, Navigation popups과 LiveRC와 같은 가벼운 웹-기반 자바스크립트 클라이언트, Vandal Fighter와 같은 엔드유저 어플리케이션, 그리고 다른 웹 사이트(툴 연구소' 유틸)등이 있습니다.

새로운 미디어위키 설치본에서 웹서비스는 기본적으로 활성화되어 있으나 관리자가 비활성화 시킬 수 있습니다.

미디어위키는 두 개의 외부에 노출된 인터페이스들을 가집니다.

예시[edit]

이 URL은 영어 위키페디아에 Main Page의 내용를 전송하도록 요청합니다.

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

이 URL에 HTTP GET 요청을 만드도록 아무 프로그래밍 언어를 사용하거나 브라우저로 이 링크를 접속하면, "Main Page"라 명명된 페이지의 현재 위키 마크업을 포함하는 JSON 문서를 받게 됩니다. Changing the format to jsonfm will return a "pretty-printed" HTML result good for debugging.

Here is the jsonfm URL as an easier-to-read clickable link.

api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=jsonfm [try in ApiSandbox]

이것이 어떻게 작동하는 지 저 URL을 조각내봅시다.

접속점[edit]

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

이것이 "접속점"입니다. 미디어위키 웹 서비스 API의 홈 페이지와 비슷합니다. https://en.wikipedia.org/wiki/이 이 웹사이트의 기초 URL 인 것처럼, 이 URL은 영어 위키피디아의 API의 기초 URL입니다.

만약 영어 위키피디아를 사용하는 프로그램을 만들고 있다면,구성되는 모든 URL은 이 기초 URL로 시작할 것이다. 만약 다른 미디어위키를 사용하고 계시다면, 그것의 다른 접속점을 찾아 대신 써야할 것입니다. 모든 위키미디어 위키들은 이 규칙을 따르는 접속점들을 가집니다.

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 version: ≥ 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로의 절대 경로가 이상한 rewrite 규칙에 의해 숨겨지지 않았다면 "편집" (또는 기록) 링크를 취하고 index.php를 api.php로 바꾸거나, 만약 아니면 기본 스크립트 경로를 사용할 수 있을 것입니다. (w/api.php 처럼)

이제 URL의 쿼리 문자열 안 매개변수로 넘어갑시다.

형식[edit]

format=json This tells the API that we want data to be returned in JSON format. 또한 format=jsonfm을 시도하여 디버깅에 좋은 HTML 버전으로 결과를 받을 수 있습니다. The API supports other output formats such as XML and native PHP, but there are plans to remove less popular formats (phab:T95715), so you might not want to use them.

기능[edit]

action=query

The MediaWiki web service API implements dozens of actions and extensions implement many more; the dynamically generated API help documents all available actions on a wiki. In this case, we're using the "query" action to get some information. The "query" action is one of the API's most important actions, and it has extensive documentation of its own. 뒤에 오는 것은 그저 한 예제의 설명입니다.

기능-지정 매개변수[edit]

titles=Main%20Page

예제 URL의 나머지는 "query" 기능에서 사용하는 매개변수들을 포함합니다. 여기서, 우리는 웹 서비스 API에게 우리는 "Main Page"라 불리는 위키 페이지에 대한 정보를 원한다고 알립니다. (%20은 퍼센트 인코딩된 스페이스입니다.) If you need to query multiple pages, put them all in one request to optimize network and server resources: titles=PageA|PageB|PageC. 더 자세한 사항은 query 문서를 참고하세요.

prop=revisions

You can request many kinds of information, or properties, about a page. This parameter tells the web service API that we want information about a particular revision of the page. 아무 판 정보도 지정하지 않는다면 API는 최신 판에 대한 정보를 제공할 것입니다, 이 URL은 최신 버전의 위키백과 메인 페이지를 가라킵니다.

rvprop=content

최종적으로, 이 매개변수는 웹 서비스 API에게 페이지의 최신 판을 원한다고 알립니다. 만약 대신 rvprop=content|user을 쓴다면, 최신 판의 내용과 가장 최근의 판을 만든 사용자와 이름을 받을 것입니다.

이것은 그저 하나의 예제입니다. 쿼리들은 여기서 더 자세히 설명되어 있으며,API 레퍼런스는 가능한 기능들 모두와 rvprop에 들어 갈 수 있는 값들과, 기타 등등을 열거합니다.

San Francisco Hackathon January 2012에서의 Roan Kattouw의 API 입문


시작하기[edit]

미디어위키 웹 서비스 API를 사용하기 전에, 이 문서들을 반드시 읽어주십시오.

Beyond that point, what you need to read depends on what you want to do. The right-hand menu links to detailed, task-specific documentation, and some more general guidelines are given below.

Identifying your client[edit]

When you make HTTP requests to the MediaWiki web service API, be sure to specify a User-Agent header that properly identifies your client. Don't use the default User-Agent provided by your client library, but make up a custom header that identifies your script or service and provides some type of means of contacting you (e.g., an e-mail address).

An example User-Agent string might look like:

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

On Wikimedia wikis, if you don't supply a User-Agent header, or you supply an empty or generic one, your request will fail with an HTTP 403 error (cf. m:User-Agent policy). Other MediaWiki installations may have similar policies.

If you are calling the API from browser-based JavaScript, you won't be able to influence the User-Agent header: the browser will use its own. To work around this, use the Api-User-Agent header:

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

In PHP, you can identify your user-agent with code such as this:

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

Or if you use cURL:

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

Logging in[edit]

Your client will probably need to log in to MediaWiki, possibly via its own user account. See the login manual page for details.

API etiquette[edit]

Please also read: API:Etiquette

If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. More information about rate-limiting, concurrency, and general API etiquette can be found at API:Etiquette. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. If you make a request for api.php?....titles=Foo|Bar|Hello, and cache the result, then a request for api.php?....titles=Hello|Bar|Hello|Foo will not go through the cache — even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.

Useful links[edit]

The menu bar on the right side of this page links to more detailed, task-specific documentation. Here are some links having to do with the API as a whole:

Archived links[edit]

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Main_page/ko&oldid=2301101"