Jump to content
MediaWiki

API:エチケット

From mediawiki.org
This page is a translated version of the page API:Etiquette and the translation is 70% complete.
このページは MediaWiki 操作 API の説明文書の一部です。
MediaWiki 操作 API
基本
認証
利用者とアカウント
ページのオペレーション
検索
開発者向けユーティリティ
チュートリアル
表 · 話 · 編
このページの要旨:
  • 連絡先情報を含んだ情報提供のための User-Agent 文字列を設定してください。そうしないと、通知なしに IP ブロックされる場合があります。
  • 新しいリクエストを送信する前に、1 つのリクエストが終了するのを待ってシリーズでリクエストを行ってください。
  • Perform grouped updates via one single editEntity, for all languages and for labels, descriptions, and aliases at once.

このページでは、APIを使用する上で従うべきベストプラクティスについて説明します。

挙動

リクエストの上限

リクエストには制限はありませんが、サイトがダウンしないよう配慮しましょう。 システム管理者は、あなたがサイトを不安定にすると、あなたをブロックすることがあります。

同時に複数個のリクエストを送るのではなく、1つづつ、前のリクエストが完了してから次のリクエストを送りましょう。 また、複数のアイテムを1つのリクエストで問い合わせることが推奨されます。

  • 各タイトルごとにリクエストを発行するのではなく、利用可能な場合は常にパイプ文字(|)を利用してください。例: titles=PageA|PageB|PageC。
  • 他のリクエストの結果ごとに新しいリクエストを発行するのではなく、代わりにgenerator を使用してください。
  • 利用バンド幅を減らすために、Accept-Encoding: gzip を設定して、GZip圧縮を有効にしてください。

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. 自分にかかっている制限は、action=query&meta=userinfo&uiprop=ratelimitsAPI エンドポイントにアクセスすることで見ることができます。

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.

版の構文解析

revid パラメーターで版番号を指定して結果を取得するクエリを実行することもできますが、これはサーバーにとって負荷が高い処理です。 特定の版を取得するには、oldid パラメーターを使用します。例:

maxlag パラメーター

タスクが対話的ではない場合 (つまり、利用者が処理結果を待機しない場合) は、maxlag パラメーターを使用すべきです。 maxlag パラメータの値は秒数を整数で指定する必要があります。 例:

これにより、サーバーの負荷が高い場合に、タスクの実行を防止できます。 数値が高い程アグレッシブで、低い方が良いです。

詳細は Manual:maxlag パラメーター を参照してください。

User-Agent ヘッダー

叙事的なUser-Agentヘッダーの設定が最善です。 そのためには、User-Agent: クライアント名/バージョン (連絡先情報、例: 利用者名、メールアドレス) フレームワーク/バージョン... を使用します。 PHP の例: 

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

人気があるウェブ ブラウザーの User-Agent をコピーしないでください。 これにより、問題が発生した場合に発生源を特定するのが容易になります。

ブラウザー ベースの JavaScript から API を呼び出す場合、ブラウザーによっては User-Agent ヘッダーに影響を与えられない場合があります。 回避するには、Api-User-Agentヘッダーを使用してください。

データフォーマット

すべての新規API利用者はJSONを使用する必要があります 。 詳細は API:データ形式 を参照してください。

Caching

データを一定期間キャッシュできる場合は、同じデータを繰り返しリクエストしないようにキャッシュする必要があります。 一部のクライアントは自身でデータをキャッシュできますが、他のクライアント (特に JavaScript クライアント) ではそれが不可能な場合があります。

POST requests

ウェブ サービス API からデータを読み取る際には、可能であれば POST ではなく GET リクエストを使用するようにし、後者はキャッシュできず、マルチ データセンター構成 (ウィキメディアのサイト群を含む) ではより遠いデータセンターに送られる場合があることに注意してください。

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. 詳細は m:ユーザーエージェントのポリシー を参照してください。

Rate limits

In addition to rate limits based on user actions, API requests to Wikimedia wiki are subject to API rate limits .

パフォーマンス

操作 API を使用して大量のデータをダウンロードすることは常に非常に効率的ではありません。 ウィキメディアのウィキ群では、大量のデータを効率的に取得するための高速な方法があります。詳細は m:Research:Data と wikitech:Portal:Data Services を参照してください。

関連項目

Code stewardship

AltStyle によって変換されたページ (->オリジナル) /