Whether it’s a script, integration, or app you’re using — if it’s making external REST API requests, it will be affected by rate limiting. Until now, you could send an unlimited number of REST API requests to retrieve data from Crowd, so we’re guessing you haven’t put any restrictions on your code. When admins enable rate limiting in Crowd, there’s a chance your requests will get limited eventually, so we want to help you prepare for that.

はじめる前に

To better understand the strategies we’ve described here, it’s good to have some some basic knowledge about rate limiting in Crowd.

クイック リファレンス

戦略

We’ve created a set of strategies you can apply to your code so that it works with rate limits. From very specific to more universal, these reference strategies will give you a base, which you can further refine to make an implementation that works best for you.

1. エクスポネンシャル バックオフ

この戦略はもっとも汎用性が高く、実装も容易です。レート制限システムに固有の HTTP ヘッダーや情報を期待することがないため、同じコードをアトラシアン スイート全体で使用できます (アトラシアン製品以外でも高い確率で使用できます)。この戦略を使用するための基本事項は、自身がすでに制限されているか (リクエストが許可されるまで待機および再試行)、制限されていないか (制限に到達するまでリクエストを送信し続ける) を確認することです。

汎用的。あらゆるレート制限システムで使用できます。

制限やレート制限システムについての広範な知識は不要です。

High impact on a Crowd instance because of concurrency. We’re assuming most active users will send requests whenever they’re available. This window will be similar for all users, making spikes in Crowd performance. The same applies to threads — most will either be busy at the same time or idle.

予測不可能。いくつかの重要なリクエストを行う必要がある場合、すべてが確実に成功するとは限りません。

この戦略の要約

コードの調整方法の概要を以下に示します。

1. アクティブ: 429 が発生するまでリクエストを作成します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。

2. タイムアウト: 429 を受け取ったらタイムアウトを開始します。最初は 1 秒に設定します。選択したタイムアウト時間よりも長めに (最大で 50%) 待機することをおすすめします。

3. 再試行: タイムアウト時間が経過したら、もう一度リクエストを行います。

   1. Success: If you get a 2xx message, go back to step 1 and make more requests.

   2. Limited: If you get a 429 message, go back to step 2 and double the initial timeout. You can stop once you reach a certain threshold, like 20 minutes, if that’s enough to make your requests work.

この戦略を使用すれば、トークンを可能な限り迅速に枯渇させ、後続のリクエストを作成して、サーバー側のレート制限の状態をアクティブに監視できます。レートが制限を超えた場合は 429 を受け取ります。

2. 時間指定のバックオフ

This strategy is a bit more specific, as it’s using the retry-after header. We’re considering this header an industry standard and plan to use it across the Atlassian suite, so you can still be sure the same code will work for Jira, Confluence and Bitbucket, Data Center and Cloud, etc. This strategy makes sure that you will not be limited, because you’ll know exactly how long you need to wait before you’re allowed to make new requests.

Universal, works with any rate limiting system within the Atlassian suite (and other products using retry-after) – Jira, Confluence and Bitbucket, Data Center and Cloud, etc.

制限やレート制限システムについての広範な知識は不要です。

High impact on a Crowd instance because of concurrency. We’re assuming most active users will send requests whenever they’re available. This window will be similar for all users, making spikes in Crowd performance. The same applies to threads — most will either be busy at the same time or idle.

この戦略の要約

コードの調整方法の概要を以下に示します。

1. アクティブ: リクエストを作成し、新しいトークンに必要な待機秒数を示す retry-after レスポンス ヘッダーを確認します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。

   1. 成功: ヘッダーに 0 と返された場合、追加のリクエストをすぐに作成できます。

   2. Limited: If the header has a number greater than 0, for example 5, you need to wait that number of seconds.

2. タイムアウト: ヘッダーが 0 よりも大きい場合、ヘッダーで指定された秒数でタイムアウトを開始します。ランダムな端数 (最大 20％) でタイムアウトを増やすことをご検討ください。

3. 再試行: ヘッダーで指定されたタイムアウトが経過したら、ステップ 1 に戻って追加のリクエストを作成します。

この戦略を使用すれば、トークンを可能な限り迅速に枯渇させ、新しいトークンを取得するまでリクエストを停止できます。対象のコードがトークンを消費する唯一のエージェントで、リクエストを同時に送信する場合、429 が返されることはありません。

3. レート調整

This strategy is very specific and expects particular response headers, so it’s most likely to work for Crowd Data Center only. When making requests, you’ll observe headers returned by the server (number of tokens, fill rate, time interval) and adjust your code specifically to the number of tokens you have and can use.

It can have the least performance impact on a Crowd instance, if used optimally.

特に大量のトラフィックを必要とする連携で強く推奨されます。

安全。送信するすべてのリクエストが確実に許可されます。また、カスタマイズの幅が広くなります。

非常に具体的。特定のヘッダーとレート制限システムに依存します。

この戦略の要約

コードの調整方法の概要を以下に示します。

1. アクティブ: リクエストを作成してすべてのレスポンス ヘッダーを確認します。

2. 調整: 各リクエストで、次のヘッダーに基づいてレートを再計算します。

   1. x-ratelimit-interval-seconds: 時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。

   2. x-ratelimit-fillrate: 時間間隔ごとに取得するトークンの数。

   3. retry-after 新しいトークンに必要な待機時間 (秒)。コード側のレートでは、待機時間をこの値よりも長く想定するようにします。

3. 再試行: 429 が返される場合、ヘッダーを正確に使用していない可能性があります。コードをさらに調整して再度発生しないようにする必要があります。retry-after ヘッダーを使用して、トークンを利用可能な場合にのみリクエストを作成するようにすることができます。

コードのカスタマイズ

ニーズに応じて、この戦略は次のような場合に役立ちます。