レート制限用にコードを調整する

レート制限でインスタンスの安定性を改善する

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

スクリプト、連携、またはアプリのいずれを使用している場合も、それらが外部 REST API リクエストを行う場合、レート制限の影響を受けます。これまでは無制限の REST API リクエストを送信して Confluence からデータを取得できました。このため、コード側で制限が設定されている可能性は低いと弊社では考えています。管理者が Confluence でレート制限を有効化すると、リクエストが最終的には制限される可能性があります。このページではレート制限への準備について説明します。

はじめる前に

ここで説明した戦略を理解するには、Confluence でのレート制限について基本的な知識を持っていることが推奨されます。ご不明な点がある場合は、「レート制限でインスタンスの安定性を改善する」に移動し、最初の段落をご確認ください。

クイック リファレンス


リクエスト コード...

成功: リクエストが成功すると、2xx コードが表示されます。

エラー: リクエストが失敗すると、4xx コードが表示されます。レートが制限されている場合、429 (too many requests) になります。

HTTP ヘッダー...

次の HTTP ヘッダーが、レート制限の影響を受けるすべての認証済みリクエストに追加されます。

ヘッダー

説明

X-RateLimit-Limit保有できるリクエスト (トークン) の最大数。この制限に到達した後は、新しいトークンがバケットに追加されません。管理者はこれを最大リクエスト数として設定します。
X-RateLimit-Remainingトークンの残りの数。この値はリクエストの実行時には非常に正確ですが、常に正確であるとは限りません。
X-RateLimit-Interval-Seconds

時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。

X-RateLimit-FillRate

時間間隔ごとに取得するトークンの数。管理者は、これを許可されるリクエスト数として設定します。

retry-after

新しいトークンを取得するまでに待機する必要がある時間。まだトークンが残っている場合は 0 を示し、すぐに追加でリクエストを実行できることを意味します。


戦略

アトラシアンでは、レート制限がある場合にも動作するよう、コード戦略に適用できる一連の戦略を作成しました。非常に具体的な戦略からより汎用性のあるものまでのこのようなリファレンス戦略を基盤とし、さらに調整を加えることで、お客様に最適な実装を実現できます。

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

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

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

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

(error) 同時性により、Confluence インスタンスに大きな影響を与えます。ほとんどのアクティブなユーザーが、利用可能なタイミングでリクエストを送信すると想定します。この時間枠はすべてのユーザーで同様なため、Confluence のパフォーマンスでスパイクが発生します。同じことがスレッドにも適用され、ほとんどが同時にビジーまたはアイドル状態になります。

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

この戦略の要約

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

  1. アクティブ: 429 が発生するまでリクエストを作成します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。
  2. タイムアウト: 429 を受け取ったらタイムアウトを開始します。最初は 1 秒に設定します。選択したタイムアウト時間よりも長めに (最大で 50%) 待機することをおすすめします。
  3. 再試行: タイムアウト時間が経過したら、もう一度リクエストを行います。
    1. 成功: 2xx メッセージを受け取ったら、ステップ 1 に移動してリクエストをさらに作成します。
    2. 制限状態: 429 メッセージを受け取ったら、ステップ 2 に戻ってタイムアウト値を初期値の 2 倍にします。リクエストが機能するために十分な特定のしきい値 (20 分など) に到達したら、それ以上値を増やす必要はありません。

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

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

この戦略は retry-after ヘッダーを使用しているため、より具体的です。弊社ではこのヘッダーは業界標準であると考え、アトラシアン スイート全体で使用する予定です。このため、同じコードを Bitbucket および Confluence、Server および Cloud で使用できます。この戦略では新しいリクエストを作成するまでに必要な待機時間を正確に把握できるため、確実に制限されないようにすることができます。

(tick) 汎用的。アトラシアン スイート (および retry-after を使用する他の製品) のレート制限システムで機能で使用します。例: Bitbucket および Confluence、Server および Cloud。

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

(error) 同時性により、Confluence インスタンスに大きな影響を与えます。ほとんどのアクティブなユーザーが、利用可能なタイミングでリクエストを送信すると想定します。この時間枠はすべてのユーザーで同様なため、Jira のパフォーマンスでスパイクが発生します。同じことがスレッドにも適用され、ほとんどが同時にビジーまたはアイドル状態になります。

この戦略の要約

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

  1. アクティブ: リクエストを作成し、新しいトークンに必要な待機秒数を示す retry-after レスポンス ヘッダーを確認します。レート制限に到達したタイミングを正確に把握できるよう、同時性を最小限に抑えるようにします。
    1. 成功: ヘッダーに 0 と返された場合、追加のリクエストをすぐに作成できます。
    2. 制限状態: ヘッダーが 0 より大きい数の場合 (5 など)、その秒数待機する必要があります。
  2. タイムアウト: ヘッダーが 0 よりも大きい場合、ヘッダーで指定された秒数でタイムアウトを開始します。ランダムな端数 (最大 20%) でタイムアウトを増やすことをご検討ください。
  3. 再試行: ヘッダーで指定されたタイムアウトが経過したら、ステップ 1 に戻って追加のリクエストを作成します。

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

3. レート調整

この戦略は非常に具体的で、特定のレスポンス ヘッダーを期待します。このため、Confluence Data Center でのみ機能する可能性が高いです。リクエストの作成時に、サーバーから返されたヘッダーを確認し (トークンの数、入力レート、時間間隔)、所有しているトークンと使用可能なトークンの数に合わせてコードを調整します。

(tick) 最適な方法で使用すると、Confluence インスタンスに与える影響を最小限に抑えることができます。

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

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

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

この戦略の要約

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

  1. アクティブ: リクエストを作成してすべてのレスポンス ヘッダーを確認します。
  2. 調整: 各リクエストで、次のヘッダーに基づいてレートを再計算します。
    1. x-ratelimit-interval-seconds: 時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。
    2. x-ratelimit-fillrate: 時間間隔ごとに取得するトークンの数。
    3. retry-after 新しいトークンに必要な待機時間 (秒)。コード側のレートでは、待機時間をこの値よりも長く想定するようにします。
  3. 再試行: 429 が返される場合、ヘッダーを正確に使用していない可能性があります。コードをさらに調整して再度発生しないようにする必要があります。retry-after ヘッダーを使用して、トークンを利用可能な場合にのみリクエストを作成するようにすることができます。

コードのカスタマイズ

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

長期的に大量のリクエストを送信...

ヘッダーに従うことで、保有しているトークン数、新しいものを取得できるタイミング、およびその数を把握できます。ここでもっとも便利なヘッダーは x-ratelimit-interval-secondsx-ratelimit-fillrate です。これらは、各時間間隔ごとに利用可能なトークンの数を示します。これは、リクエスト作成の最適な頻度を選択するのに役立ちます。

複雑なオペレーションを最適なタイミングで実行...

連続したリクエストすべてを作成するのに十分なトークンを確保できるまで、複雑なオペレーションの実行を待機できます。これにより、システムが一貫しない状態になるリスクを減らすことができます (例: 自身の作業で 4 件のリクエストを作成する必要があるが、2 件しか作成できない場合など)。もっとも便利なヘッダーは、現在保有しているトークンの数を示す x-ratelimit-remaining と、新しいトークンを取得するのに必要な待機時間を示す x-ratelimit-interval-seconds です。 

より高度なトラフィック シェーピング戦略を作成...

ヘッダーで返されたすべての情報を使用することで、自社に最適な戦略を作成したり、ここで説明した戦略を混在させたりすることができます。例:

1 日に 1 回のみリクエストを作成する場合、累積可能な最大リクエスト数 (x-ratelimit-limit) に焦点を当てるか、Confluence の特定のアクションでアプリによるリクエストの作成をトリガーする場合は、トークンの残りの数 (x-ratelimit-remaining) を利用します。

スクリプトが Confluence Data Center と他のアプリケーションの両方で機能する必要がある場合、Confluence のすべてのヘッダーを使用し、アプリが異なるソフトウェアを検知する場合は汎用の再試行またはリクエスト コードに焦点を当てます。

最終更新日 2023 年 7 月 6 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.