Definition
APIのレート制限はどのように適用されますか。
上限は組織ごと、エンドポイントの区分ごとに適用され、すべての応答のヘッダーで上限、残量、リセット時刻が通知されます。公開のパスポート解決は貴社のクォータとは別に計測します。スキャンの急増が発行パイプラインの枠を食いつぶしてはならないためです。
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
クラス
すべてのエンドポイントが同じ基準で計測されるわけではありません
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
ヘッダー
すべての応答から分かること
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));クライアント設計
行儀のよいクライアントの振る舞い
ヘッダーを読む
記載された数値を前提にせず、現在の上限に追随します。
ジッターを入れて再試行
ランダムな遅延を入れ、並列ワーカーが足並みをそろえて再試行しないようにします。
一括処理経路を使用
既存データの取り込みは一括処理で行います。単一リソースのエンドポイントをループで呼び出すのではありません。
パイプラインを分離する
発行と報告を別々のキーで行い、一方が他方を枯渇させないようにします。
再試行回数に上限を設ける
無限に再試行せず、打ち切って失敗を明示します。
上限に達する前に警告
残りの上限を通知するため、最初の兆候が本番環境の429になることはありません。
回答
よくある質問
実際の上限はどれくらいですか。
これはご契約のプランとエンドポイントの区分によって決まり、ここではなくご契約書に記載されます。公開された数値は1回のリリースで古くなり、それを前提に見積もった連携担当者は本番で実際の上限に直面することになります。代わりにヘッダーをお読みください。常に最新です。
クライアントは429にどう対応すべきですか。
`Retry-After` があればそれに従い、なければジッターを入れた指数バックオフを行い、試行回数に上限を設けてください。即座に、あるいは多数のワーカーが一定間隔で再試行すると、短時間の制限が持続的な制限に変わります。小さな問題を障害へ変える、いわゆるサンダリングハードです。
公開のパスポート解決にも同じレート制限がかかりますか。
いいえ。解決は公開・キャッシュ可能で、本質的に急増するものです。したがって貴社のクォータではなく、キャッシュとエッジの容量によって制御されます。ある製品が話題になったからといって、発行パイプラインが依存するクォータを消費すべきではありません。だから二つの経路は別々に計測します。
大量の既存カタログはどう読み込むべきですか。
単一リソースのエンドポイントをループするのではなく、一括インポート経路を使ってください。一括処理はスループット向けに設計されており、ポーリングするジョブとして非同期に実行されます。リソース単位のエンドポイントはレイテンシー向けの設計です。使い分けを誤ることが、自ら招くレート制限の最も一般的な原因です。
上限はキー単位ですか、組織単位ですか。
組織単位で適用し、キー単位で可視化します。サービスごとにキーを分けている場合、これが効いてきます。挙動のおかしい一つのサービスが共有枠を食いつぶし得るからです。キー別の内訳があれば、消去法ではなく短時間で特定できます。