【重要なお知らせ】BacklogはAPIへの高頻度なリクエスト送信を制限します

Backlogを安定して運用し全てのお客様に安心してご利用いただくために、APIサーバに対してユーザーが送信できる1分間あたりのリクエスト数を制限します。対象はAPIキーをご利用のユーザーのうち「1分間あたりのリクエスト数が特に多い方」となります。

すでにご利用頂いているスペースにつきましては、現在の業務に与える影響を鑑みて、6ヶ月の準備期間をおいて2021年7月末より制限を適用します。本日以降に利用を開始されたスペースには本日より制限を適用します。

現在のAPIキーのユーザーのごく一部しか抵触しない見込みの、緩い制限となっておりますが、ご利用中のお客様には、リクエストの送信間隔の調整や、リクエストの再送処理の実装を推奨します。

制限の背景、適用される制限、制限の対象と適用スケジュール、制限にともないお客様でご対応が必要なケースについてご説明します。

制限の背景

一部のお客様からAPIへの高頻度なリクエスト送信が行われ、その結果Backlogの機能の一部が不安定になる障害が、過去に何度か発生しています。

これまでは、原因となるリクエストの送信元であるお客様にご連絡し、送信間隔を調整いただくか、急を要する場合は弊社にてAPIキーを無効にするという対策を行ってまいりました。しかし、このような対策では障害の回復までに時間がかかり、他のお客様のご利用の妨げとなっておりました。

このような障害を未然に防ぐために、本日以降に利用を開始されたスペースに対して、BacklogのAPIへの、高頻度なリクエストに対する制限（以下、レート制限）を導入いたします。すでにご利用頂いているスペースにつきましては、現在の業務に与える影響を鑑み、6ヶ月の準備期間をおいて2021年7月末より導入いたします。

今回導入するレート制限の機能では、通常時は緩い制限を行い、障害またはサービス品質低下の予兆が見られた場合に限り、強い制限を実施します。お客様の利便性をなるべく下げないために、通常時は全APIユーザーのごく一部にしか抵触しない見込みの緩い制限となっております。しかし、APIキーを利用している機能は多数ありますので、念のため以下の内容を必ずご確認お願いします。

適用される制限

分単位およびユーザー単位のレート制限

レート制限は、特定のお客様からのリクエストが短時間に集中した場合に、それらのリクエストを拒否することで、他のお客様が安定してBacklogをご利用いただけることを目的としています。

そのため、この制限は分単位、およびユーザー単位で行います。

あるユーザーからのリクエスト件数が、1分以内に上限を超えた場合（※）、そのユーザーからのリクエストには429 Too Many Requests応答を返します。最初のリクエストから1分が経過すると、リクエスト数はリセットされます。

（※件数の目安については 「4.1. Backlog APIを用いた自作のソフトウェアを利用している」でご紹介しております）

例えば、あるユーザーAが12:34:10からAPIリクエストを送信し続けて、12:34:30に上限に達したとします。その後のAPIリクエストは429応答とともに拒否されますが、12:34:10から1分後の12:35:10以降はリクエストが受け付けられます。この12:34:30〜12:35:10の間も、他のユーザーからのリクエストは通常通りに許可されます。

APIサーバの応答には、以下のHTTPヘッダが新たに追加されます。これらのヘッダを確認することで、レート制限の動作の詳細を確認できます。

この制限はAPIキー単位ではなく、ユーザー単位であることにご注意ください。あるユーザーがAPIキー1とAPIキー2を作成した場合、APIキー1が制限を受けている時間には、APIキー2も同じ制限を受けます。

APIの種類ごとに異なるレート制限

Backlogの安定した運用と利便性を両立させるために、システムへの負荷が高いリクエストには厳しい制限を加える一方で、負荷が低いリクエストには緩い制限を行います。

レート制限のために、既存のAPIを以下の4種類に分類します。そして、読み込み、更新、検索、アイコン取得の順に厳しい制限を設けます。

■ API制限の厳格レベル

↑緩い

• 読み込み
  • アイコンおよび検索に含まれないGETリクエスト
• 更新
  • POST、PATCHおよびDELETEリクエスト
• 検索（以下のGETリクエスト）
  • 課題一覧の取得
  • 課題数の取得
  • Wikiページ一覧の取得
  • Wikiページ数の取得
• アイコン
  • スペースアイコン画像の取得
  • ユーザーアイコンの取得
  • プロジェクトアイコンの取得
  • グループアイコンの取得
  • チームアイコンの取得

↓厳しい

レート制限の仕様の詳細は、Backlog APIドキュメントの「レート制限」の章をご確認ください。

有料プランとフリープランで異なるレート制限

Backlogに対して異常な負荷をかける攻撃（DoS攻撃）を実行しにくくするために、メールアドレスのみで作成できるフリープランのスペースに対しては、有料プランのスペースよりも厳しい制限を行います。

制限の対象と適用スケジュール

BacklogのAPIキーを利用するすべてのユーザーが対象

Backlog APIドキュメントにあるAPIを用いた自作のソフトウェアのユーザー、およびヌーラボが提供する以下のソフトウェアのユーザーが対象です。

• Googleスプレッドシートによる課題一括登録
• Backlog移行ツール
• Backlog Migration for JIRA
• Backlog Redmine Importer

ヌーラボが提供するこれらのソフトウェアは、レート制限に抵触しない頻度でリクエストを送信します。しかし、自作のソフトウェアとヌーラボ提供のソフトウェアを同時に実行した場合や、ヌーラボ提供のソフトウェアを複数同時に実行した場合には、レート制限に抵触する可能性があります。

すでにご利用いただいているスペース

すでにご利用頂いているスペースにつきましては、現在の業務に与える影響を鑑み、6ヶ月の準備期間をおいて2021年7月末より制限を適用します。

ただし、レート制限の動作をご確認いただくために、レート制限のためのヘッダ（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset）の追加は本日より行います。X-RateLimit-Remainingの値が0になっているリクエストがある場合は、レート制限の適用後にリクエストが拒否される可能性があります。現時点では、リクエスト数が上限に達しても、リクエストの拒否は行いません。

本日以降に利用を開始されたスペース

本日以降に利用を開始されたスペースには本日より制限を適用します。

制限にともないお客様でご対応が必要なケース

Backlog APIを用いた自作のソフトウェアを利用している

自作のソフトウェアでのリクエスト送信の頻度をご確認いただき、もし送信頻度が以下の限界値を超えている場合は必ず、「5. Backlog API利用時の推奨事項」を参考に送信頻度の調整をお願いします。

送信頻度の調整後は、X-RateLimit-Remainingの値が0になるかどうかをご確認いただくことで、レート制限に該当するかどうかをご確認いただけます。

なお、Backlogのシステムに高い負荷がかかり、障害またはサービス品質低下の予兆が見られた場合には、上記の限界値よりも低い頻度で429 Too Many Requests応答が返される可能性があります。業務上重要なソフトウェアにつきましては、送信頻度の調整に加え、429応答を受信した1分後にリクエストを再送する処理を実装することを推奨いたします。

Backlog APIを用いたソフトウェアを2個以上併用している

同じAPIキーで、Backlog APIを用いたソフトウェアを同じ時刻に併用しないように、ソフトウェア利用方法の見直しをお願いいたします。

フリープランを利用している

レート制限の導入に伴い、フリープランでは以下のソフトウェアを利用できなくなります。

• Googleスプレッドシートによる課題一括登録
• Backlog移行ツール
• Backlog Migration for JIRA
• Backlog Redmine Importer

フリープランでこれらのソフトウェアを利用されている場合は、2021年7月末までにこれらのソフトウェアの利用を終了していただくか、有料プランへのアップグレードをお願いいたします。

Backlog API利用時の推奨事項

レート制限に抵触しないために、Backlog APIを用いて自作ソフトウェアを開発する際は、以下の事項を守って開発することを推奨します。

• 1つのソフトウェアから、同時に複数のリクエストを送信しない。1つのリクエストに対して応答が返されてから、次のリクエストを送信する。
• 大量の更新・検索リクエストを送信する必要がある場合は、リクエストの送信ごとに最低1秒の待ち時間をおく。
• 429応答が返された場合は、1分後にリクエストを再送する。どうしても待ち時間を1分よりも短くしなければならない場合は、X-RateLimit-Resetの値をもとに待ち時間の長さを調節する。X-RateLimit-Resetの詳細は、Backlog APIドキュメントの「レート制限」の章を参照のこと。
• 定期的に実行するソフトウェア（定時バッチなど）の場合、過去のリクエスト結果をキャッシュし、なるべくリクエスト数を減らす。
• 定期的に実行するソフトウェア（定時バッチなど）の場合、更新日などの条件を使い、なるべく取得するデータ件数を減らす（例：課題一覧の取得のupdatedSinceパラメーター）。

一方、このレート制限を回避するために、1つのソフトウェアが、複数のユーザーのAPIキーを用いてリクエストを送信することは推奨しません。そのようなリクエストが発見された場合、さらに厳しいレート制限の適用や、APIキーの利用停止をさせていただく可能性があります。

本制限についてのご協力をお願いいたします

APIサーバのレート制限の導入により、ご対応が発生するお客様もいらっしゃいます。ご不便をおかけすることになり申し訳ございません。Backlogを安定して運用し、全てのお客様に安心して日々の業務でご利用いただくためにも、ぜひご理解とご協力いただければ幸いです。

本件に関するご質問やフィードバックは問い合わせより受け付けております。ご不明な点がございましたらお気軽にお問い合わせくださいませ。