API:FAQ/zh

注意：此页面仍在建立中

请同时阅读quick start guide. 该指南回答了这里没有提及的问题，并汇总了其他一些有用的页面.

获取帮助？

 * 1) Read this FAQ
 * 2) Try to find the answer to your question in the API documentation here or on the self-documenting API home page
 * 3) If you can't find the answer to your question on the web,
 * 4) * you can ask your question on the mediawiki-api mailing list.
 * 5) * Create a Wikimedia account (if you don't have one already) and add a new topic on the API discussion page.
 * 6) * Ask on IRC in the channel on the Freenode network.

报告新bug或功能请求？
如果你在API中发现bug或提交新功能，可以将其报告至Phabricator. 若要报告bug，请先阅读search for existing bugs，在页面中选择“MediaWiki”产品->“API”组件并查看该bug中是否已经存在. 若所报告的bug或新功能存在于扩展组件中（如AbuseFilter或FlaggedRevs），请将它们提交到对应的组件中（在"MediaWiki extensions"列表下）.

figure out what action or submodule to call?
The MediaWiki API is big, and extensions further enlarge it. Some suggestions:


 * If you're trying to get information about a page, you probably will use a prop= submodule of . Other query submodules return lists of pages and meta-information about the wiki. [ View] the generated API help of all query submodules.
 * If you see a wiki page doing something interesting after initial page load, it must be making an API request.
 * Open your browser's developer console and look for its network requests to.
 * All the code running on Wikimedia wikis is open source, so you can read the source code making API requests. One strategy to locate source code is to append  to the wiki page URL to see the message keys near where API results are presented, then you can search for this message key in the localized message files i18n/en.json of core and extensions.
 * You can view the entire expanded generated API help on one page by appending, [ here it is].

The links to generated API help above go to English Wikipedia You should browse the generated API help on the wiki where you'll be making API requests, since different wikis have different configurations and different sets of extensions.

调试API？
发送HTTP请求至api.php. 举例来说，对于英语维基百科，对应的URL是http://en.wikipedia.org/w/api.php. 大多数维基的API请求地址是相似的，大多数将URL中的index.php换成api.php即可. 在1.17前，MediaWiki支持Really Simple Discovery：每一HTML页面源码中都有一个链接指向一个相对标准偏差RSD描述符，说明在哪里可以找到API. 如果你无法在第三方维基上（不是由维基媒体基金会托管的维基）找到API的URL，可以联系该维基站点的拥有者. 某些维基禁用了API，详见.

To play with the API


 * use Special:ApiSandbox
 * enable your browser's developer console and watch net requests to api.php as you interact with the wiki

控制输出格式？
Pass  in the query string. See the list of output formats for more information. Note that effort is underway to remove all output formats except JSON, so try to use JSON whenever possible.

check if an API module is available?
You can use  to request information about the API modules and submodules (such as  ) that you want to invoke. The  array in the response must contain a   key for each module and submodule, anything missing is not available.

If an API module isn't available and you know which extension implements it, you can check if that extension is loaded by querying the siteinfo meta information for  and look for its name in the returned list.

Even if a module appears to be available, you must always handle API errors.

检测错误？
See Errors and warnings.

An error response from the API will set the  HTTP header and return an   structure. For an example error response, visit http://en.wikipedia.org/w/api.php?action=blah.

获取页面内容（wiki文本）？
If you just want the raw wikitext without any other information whatsoever, it's best to use index.php's action=raw mode instead of the API: http://en.wikipedia.org/w/index.php?action=raw&title=Main_Page. Note that this will output plain wikitext without any formatting. See also the action=raw documentation

To get more information about the page and its latest version, use the API: http://en.wikipedia.org/w/api.php?action=query&prop=revisions&titles=Main_Page. See also the documentation for the prop=revisions module.

You can retrieve 50 pages per API request: http://en.wikipedia.org/w/api.php?action=query&prop=revisions&rvprop=content&titles=Main_Page|Articles. This also works with generators.

获取页面内容（HTML）？
If you just want the HTML, it's best to use index.php's  mode instead of the API: https://en.wikipedia.org/wiki/Main_Page?action=render. See the action=render documentation.

With the advent of RESTBase, on Wikimedia wikis you can instead request the cached HTML of a page, for example https://rest.wikimedia.org/en.wikipedia.org/v1/page/html/Main_Page. Unlike  this returns a complete HTML document (i.e.    various metadata  ...  ); you could use an HTML parsing library to get the inner HTML of the   tag (see the documentation).

To get more information distilled from the wikitext at parse time (links, categories, sections, etc.), you can:


 * Query the property submodules that provide the information you need (links, categories, etc.).
 * Use the  API module. https://en.wikipedia.org/w/api.php?action=parse&page=Main_Page.

deal with 2015's API changes?
You could add  to your requests to "lock in" the sub-optimal  JSON and PHP output format and confusing query-continue behavior.

Otherwise, consider requesting the improved API in MediaWiki 1.25 and future releases by adding  to your requests.

我遇到了HTTP 403错误？
This could mean you're not passing a  HTTP header or that your   is empty or blacklisted User-Agent policy. See the quick start guide for more information. Also, it could mean that you're passing  in the query string of a GET request: Wikimedia blocks all such requests, use POST for them instead.

do I get the readapidenied error?
The wiki you're querying contains private content and requires users to log in in order to be able to read all pages. This means that a client needs to be logged in to query any information at all through the API. See the quick start guide for more information. It's not currently possible to query the contents of whitelisted pages without logging in, even though they're available in the regular user interface.

我遇到badtoken错误？
This is usually because you're either not passing a token at all (read about tokens in the documentation of the module you're using) or because you're having trouble staying logged in. It's also possible you're reusing a type of token that can't be reused (see module documentation for details) or that you're using a token that's associated with an expired session. In general, when using cached tokens, refetch the token (see API:Tokens) and try again before giving up.

do I get warnings instead of tokens (Action 'edit' is not allowed for the current user)?
You either don't have the right to execute the action you requested, or you're having trouble staying logged in.

某件事不能通过API可用？
Not all features available in the user interface are available through the API. Such features weren't implemented either because no one has gotten around to it yet or because no one has requested them. For information about filing feature requests, see above.

does my API call on Wikimedia wikis just return an HTML error?
If you use API calls with POST requests make sure that these requests don't use Content-Type: multipart/form-data. This happens for instance if you use CURL to access the API and you pass your POST parameters as an array. The Squid proxy servers which are used at frontend servers at the Wikimedia wiki farm don't handle that correctly, thus an error is returned.

Instead, use the "value1=key1&value2=key2..." notation to pass the parameters as a string, similar to GET requests.

On other wikis which you access directly it doesn't make a difference.

In addition, some software (such as cURL) send an  header for longer POST requests (>1024 bytes). The wikimedia wikis that go through Squid servers can't cope with this. If you are still getting HTML errors with post requests, and are not logged in, try setting a blank Expect header (e.g. using cURL on the command line, use the option ).

过长的API URL是否真的无法正常工作？
There is a maximum limit of the url size that can be used with the API when making GET requests. This limit varies depending on the website. Wikimedia's limit is roughly around 8100 characters. To get around this limit use POST requests instead (you may also need to set the Expect header, as described above)