レート制限用にコードを調整する
スクリプト、連携、またはアプリのいずれを使用している場合も、それらが外部 REST API リクエストを行う場合、レート制限の影響を受けます。これまでは無制限の REST API リクエストを送信して Confluence からデータを取得できました。このため、コード側で制限が設定されている可能性は低いと弊社では考えています。管理者が Confluence でレート制限を有効化すると、リクエストが最終的には制限される可能性があります。このページではレート制限への準備について説明します。
はじめる前に
ここで説明した戦略を理解するには、Confluence でのレート制限について基本的な知識を持っていることが推奨されます。ご不明な点がある場合は、「レート制限でインスタンスの安定性を改善する」に移動し、最初の段落をご確認ください。
クイック リファレンス
戦略
アトラシアンでは、レート制限がある場合にも動作するよう、コード戦略に適用できる一連の戦略を作成しました。非常に具体的な戦略からより汎用性のあるものまでのこのようなリファレンス戦略を基盤とし、さらに調整を加えることで、お客様に最適な実装を実現できます。
1. エクスポネンシャル バックオフ
この戦略はもっとも汎用性が高く、実装も容易です。レート制限システムに固有の HTTP ヘッダーや情報を期待することがないため、同じコードをアトラシアン スイート全体で使用できます (アトラシアン製品以外でも高い確率で使用できます)。この戦略を使用するための基本事項は、自身がすでに制限されているか (リクエストが許可されるまで待機および再試行)、制限されていないか (制限に到達するまでリクエストを送信し続ける) を確認することです。
汎用的。あらゆるレート制限システムで使用できます。
制限やレート制限システムについての広範な知識は不要です。
同時性により、Confluence インスタンスに大きな影響を与えます。ほとんどのアクティブなユーザーが、利用可能なタイミングでリクエストを送信すると想定します。この時間枠はすべてのユーザーで同様なため、Confluence のパフォーマンスでスパイクが発生します。同じことがスレッドにも適用され、ほとんどが同時にビジーまたはアイドル状態になります。
予測不可能。いくつかの重要なリクエストを行う必要がある場合、すべてが確実に成功するとは限りません。
この戦略の要約
コードの調整方法の概要を以下に示します。
- アクティブ: 429 が発生するまでリクエストを作成します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。
- タイムアウト: 429 を受け取ったらタイムアウトを開始します。最初は 1 秒に設定します。選択したタイムアウト時間よりも長めに (最大で 50%) 待機することをおすすめします。
- 再試行: タイムアウト時間が経過したら、もう一度リクエストを行います。
- 成功: 2xx メッセージを受け取ったら、ステップ 1 に移動してリクエストをさらに作成します。
- 制限状態: 429 メッセージを受け取ったら、ステップ 2 に戻ってタイムアウト値を初期値の 2 倍にします。リクエストが機能するために十分な特定のしきい値 (20 分など) に到達したら、それ以上値を増やす必要はありません。
この戦略を使用すれば、トークンを可能な限り迅速に枯渇させ、後続のリクエストを作成して、サーバー側のレート制限の状態をアクティブに監視できます。レートが制限を超えた場合は 429 を受け取ります。
2. 時間指定のバックオフ
この戦略は retry-after ヘッダーを使用しているため、より具体的です。弊社ではこのヘッダーは業界標準であると考え、アトラシアン スイート全体で使用する予定です。このため、同じコードを Bitbucket および Confluence、Server および Cloud で使用できます。この戦略では新しいリクエストを作成するまでに必要な待機時間を正確に把握できるため、確実に制限されないようにすることができます。
Universal, works with any rate limiting system within the Atlassian suite (and other products using retry-after) — Bitbucket and Confluence, Server and Cloud, etc.
制限やレート制限システムについての広範な知識は不要です。
同時性により、Confluence インスタンスに大きな影響を与えます。ほとんどのアクティブなユーザーが、利用可能なタイミングでリクエストを送信すると想定します。この時間枠はすべてのユーザーで同様なため、Jira のパフォーマンスでスパイクが発生します。同じことがスレッドにも適用され、ほとんどが同時にビジーまたはアイドル状態になります。
この戦略の要約
コードの調整方法の概要を以下に示します。
- アクティブ: リクエストを作成し、新しいトークンに必要な待機秒数を示す
retry-afterレスポンス ヘッダーを確認します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。- 成功: ヘッダーに 0 と返された場合、追加のリクエストをすぐに作成できます。
- 制限状態: ヘッダーが 0 より大きい数の場合 (5 など)、その秒数待機する必要があります。
- タイムアウト: ヘッダーが 0 よりも大きい場合、ヘッダーで指定された秒数でタイムアウトを開始します。ランダムな端数 (最大 20％) でタイムアウトを増やすことをご検討ください。
- 再試行: ヘッダーで指定されたタイムアウトが経過したら、ステップ 1 に戻って追加のリクエストを作成します。
この戦略を使用すれば、トークンを可能な限り迅速に枯渇させ、新しいトークンを取得するまでリクエストを停止できます。対象のコードがトークンを消費する唯一のエージェントで、リクエストを同時に送信する場合、429 が返されることはありません。
3. レート調整
この戦略は非常に具体的で、特定のレスポンス ヘッダーを期待します。このため、Confluence Data Center でのみ機能する可能性が高いです。リクエストの作成時に、サーバーから返されたヘッダーを確認し (トークンの数、入力レート、時間間隔)、所有しているトークンと使用可能なトークンの数に合わせてコードを調整します。
最適な方法で使用すると、Confluence インスタンスに与える影響を最小限に抑えることができます。
特に大量のトラフィックを必要とする連携で強く推奨されます。
安全。送信するすべてのリクエストが確実に許可されます。また、カスタマイズの幅が広くなります。
非常に具体的。特定のヘッダーとレート制限システムに依存します。
この戦略の要約
コードの調整方法の概要を以下に示します。
- アクティブ: リクエストを作成してすべてのレスポンス ヘッダーを確認します。
- 調整: 各リクエストで、次のヘッダーに基づいてレートを再計算します。
x-ratelimit-interval-seconds: 時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。x-ratelimit-fillrate: 時間間隔ごとに取得するトークンの数。retry-after新しいトークンに必要な待機時間 (秒)。コード側のレートでは、待機時間をこの値よりも長く想定するようにします。
- 再試行: 429 が返される場合、ヘッダーを正確に使用していない可能性があります。コードをさらに調整して再度発生しないようにする必要があります。
retry-afterヘッダーを使用して、トークンを利用可能な場合にのみリクエストを作成するようにすることができます。
コードのカスタマイズ
ニーズに応じて、この戦略は次のような場合に役立ちます。