API:Etykieta
| API akcji MediaWiki |
|---|
| Podstawy |
| Uwierzytelnianie |
| Konta i użytkownicy |
| Operacje na stronach |
|
| Wyszukiwanie |
| Narzędzia dla programistów |
| Samouczki |
| p · o · e |
- Set an informative User-Agent string with contact information, or you may be IP-blocked without notice.
- Make your requests in series rather than in parallel, by waiting for one request to finish before sending a new request.
- Perform grouped updates via one single
editEntity, for all languages and for labels, descriptions, and aliases at once.
This page contains the best practices that should be followed when using the Action API.
Zachowanie
Limity żądań
Nie ma ścisłych limitów dotyczących żądań odczytu, ale prosimy o bycie rozsądnym i nie spowodowanie przeciążenia strony. Większość administratorów systemów zastrzega sobie prawo do bezceremonialnego zablokowania Ciebie, jeżeli Twoje działania zagrażają stabilności strony.
Making your requests in series rather than in parallel, by waiting for one request to finish before sending a new request, should result in a safe request rate. It is also recommended that you ask for multiple items in one request by:
- Using the pipe character (
|) whenever possible e.g.titles=PageA|PageB|PageC, instead of making a new request for each title.
- Using a generator instead of making a request for each result from another request.
- Use GZip compression when making API calls by setting
Accept-Encoding: gzipto reduce bandwidth usage.
Requests which make edits, modify state or otherwise are not read-only requests, are subject to rate limiting . The exact rate limit being applied might depend on the type of action, your user rights and the configuration of the website you are making the request to. The limits that apply to you can be determined by accessing the action=query&meta=userinfo&uiprop=ratelimits API endpoint.
When you hit the request rate limit you will receive a API error response with the error code ratelimited.
When you encounter this error, you may retry that request, however you should increase the time between subsequent requests.
A common strategy for this is Exponential backoff.
Parsowanie wersji
Choć jest możliwe odpytanie o wyniki dla konkretnej wersji, jest to obciążające dla serwera.
Aby pobrać określoną wersję, użyj parametru oldid', np.:
Parametr maxlag
Jeżeli Twoje zadanie nie jest interaktywne (tj. użytkownik nie czeka na wynik), powinieneś użyć parametr maxlag.
The value of the maxlag parameter should be an integer number of seconds.
Na przykład:
Zapobiegnie to uruchomieniu Twojego zadania, kiedy serwer jest zbyt obciążony. Większe wartości oznaczają bardziej agresywne zachowanie, niższe są przyjemniejsze.
Zobacz Manual:Maxlag parameter , aby uzyskać więcej informacji.
Nagłówek User-Agent
It is best practice to set a descriptive User-Agent header.
To do so, use User-Agent: clientname/version (contact information e.g. username, email) framework/version....
Na przykład w PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Nie kopiuj user-agent'a popularnych przeglądarek (Dopóki Twój klient API nie jest aplikacją JavaScript, uruchomioną przez wspomnianą przeglądarkę poprzez Ajax; w tym przypadku nie ma możliwości zmiany user-agent). Dzięki temu jest pewność, że będzie można wyśledzić źródło problemu jeżeli takowy wystąpi.
If you are calling the API from browser-based JavaScript, you may not be able to influence the User-Agent header, depending on the browser.
To work around this, use the Api-User-Agent header.
Typy danych
All new API users should use JSON . Zobacz API:Data_formats , aby uzyskać więcej informacji.
Caching
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. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.
POST requests
Whenever you're reading data from the web service API, you should try to use GET requests if possible, not POST, as the latter are not cacheable and, in multi-datacenter configurations (including Wikimedia sites), may go to a farther data center.
In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
Guidelines for Wikimedia wikis
In addition to the best practices described above, the following guidelines apply to using the Action API to access Wikimedia wikis. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.
User-Agent policy
API requests to Wikimedia wikis must include a meaningful User-Agent header. Zobacz m:User-Agent_policy, aby uzyskać szczegóły.
Rate limits
In addition to rate limits based on user actions, API requests to Wikimedia wiki are subject to API rate limits .
Wydajność
Downloading data in bulk is not always extremely efficient using the Action API. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.
Zobacz też
- Official guidelines about API usage on Wikimedia Foundation Governance wiki
- Wikimedia Robot policy on Wikitech
- API:Main page - The quick start guide.
- Manual:Rate limits & Wikimedia APIs/Rate limits
Code stewardship
- Zarządzany przez MediaWiki Interfaces Team.
- Czat na żywo (IRC): #mediawiki-core connect
- Zgłaszanie błędów: Phabricator - MediaWiki-Action-API (Zgłoś problem)