Google Calendar API には、すべてのユーザーが公平に使用できるようにするための割り当てがあります。カレンダー API を使用する際は、次の 3 つの重要な制限事項を考慮する必要があります。
- API 使用量割り当ては、プロジェクトごとおよびユーザーごとに適用されます。詳細については、次のセクションをご覧ください。
- カレンダーの一般的な使用制限: カレンダーの使用制限を超えないようにします。
- オペレーションの上限: レート制限はいつでも適用される可能性があります。たとえば、1 つのカレンダーに連続して書き込もうとした場合などです。
Calendar API の使用量割り当てのタイプ
次の 2 種類の割り当てが適用されます。
- プロジェクトあたりの 1 分あたりのリクエスト数: Google Cloud プロジェクトによって行われたリクエストの数です。
- 1 分、1 プロジェクト、1 ユーザーあたり: Cloud プロジェクト内の特定のユーザーが実行したリクエストの数。この上限は、ユーザー間で公平に利用状況を分配できるようにすることを目的としています。
割り当てはスライディング ウィンドウを使用して 1 分ごとに計算されます。そのため、1 分間に分単位の割り当てを超えるトラフィックが急増すると、次のウィンドウでレート制限が行われ、平均使用量が割り当て内に収まるようになります。
いずれかの割り当てを超えると、レートが制限され、クエリに対して 403 usageLimits ステータス コードまたは 429 usageLimits ステータス コードが返されます。この場合は、次の操作を行えます。
- 指数バックオフを使用する、トラフィック パターンをランダム化する、プッシュ通知を使用するなど、すべてのベスト プラクティスを実践してください。
- プロジェクトが拡大し、ユーザーが増えた場合は、プロジェクトごとの割り当ての増加をリクエストできます。
- ユーザーごとの割り当て上限に達した場合は、次の操作を行うことができます。
- サービス アカウントを使用する場合は、ユーザーに負荷を割り当てるか、複数のサービス アカウント間で負荷を分割します。
- ユーザーあたりの割り当ての増加をリクエストできますが、一般に、デフォルト値を超えて増加させることはおすすめしません。アプリケーションが他の種類の制限（一般的なカレンダーの使用制限や運用上の制限など）に達する可能性があります。
割り当て増加のリクエスト
プロジェクトの使用量上限を確認して変更する手順、または割り当ての増加をリクエストする手順は次のとおりです。
- プロジェクトの請求先アカウントをまだ持っていない場合は、1 つ作成します。
- API Console で API ライブラリの [有効な API] ページに移動し、リストから API を選択します。
- 割り当て関連の設定を表示および変更するには、[割り当て] を選択します。使用統計情報を表示するには、[使用量] を選択します。
指数バックオフを使用する
リクエストのレートを遅くする必要がある場合は、403「usageLimits」レスポンスまたは 429 レスポンスを返します（エラーに関する完全なドキュメントをご覧ください）。これは致命的なエラーではないため、短い間隔でリクエストを再試行することが想定されています。リクエストが依然として速すぎる場合は、再度確認します。この処理を正しく行うには、リクエスト間の遅延が時間とともに増加することが重要です。
通常は、切り捨て型指数バックオフを使用する必要があります。Cloud Storage のドキュメントで、この仕組みと推奨アルゴリズムについて詳しく説明しています。Google クライアント ライブラリを使用している場合、通常は自動的に処理されます。ライブラリのドキュメントをご覧ください。通常は、独自のコードを記述するのではなく、ライブラリ実装を使用する必要があります。
トラフィック パターンをランダム化する
カレンダー クライアントは、複数のクライアントが同時にオペレーションを実行することで、トラフィック パターンが急増する傾向があります。たとえば、カレンダー クライアントの一般的な悪い習慣として、午前 0 時に完全同期を行うことがあります。これにより、1 分あたりの割り当てを超え、レート制限とバックオフが発生する可能性が非常に高くなります。
これを回避するには、可能な限り、トラフィックを 1 日を通して分散させます。クライアントが毎日同期する必要がある場合は、クライアントにランダムな時間（クライアントごとに異なる）を決定してもらいます。定期的にオペレーションを実行する必要がある場合は、間隔を +/- 25% 変更します。これにより、トラフィックがより均等に分散され、ユーザー エクスペリエンスが大幅に向上します。
プッシュ通知を使用する
一般的なユースケースは、ユーザーのカレンダーで何かが変更されるたびにアクションを実行したい場合です。ここでアンチパターンとなるのは、対象となるすべてのカレンダーを繰り返しポーリングすることです。これにより、割り当てがすぐに使い果たされます。たとえば、アプリケーションに 5,000 人のユーザーがいて、各ユーザーのカレンダーを 1 分に 1 回ポーリングする場合、作業を行う前に、少なくとも 5,000 の分単位の割り当てが必要になります。
サーバーサイド アプリケーションはプッシュ通知に登録できます。これにより、関心のあることが発生したときに通知を受け取ることができます。これらは設定に手間がかかりますが、割り当てを大幅に効率的に使用でき、ユーザー エクスペリエンスが向上します。通知を受け取る eventType を指定してください。詳しくは、プッシュ通知をご覧ください。
サービス アカウントによる適切なアカウンティング
アプリケーションがドメイン全体の委任を使用してリクエストを実行している場合、デフォルトでは、権限を借用しているユーザーではなく、サービス アカウントに対して「プロジェクトあたりのユーザーあたりの 1 分あたりの」割り当てが課金されます。つまり、複数のユーザーのカレンダーで動作している場合でも、サービス アカウントの割り当てが不足してレート制限される可能性があります。これを避けるには、quotaUser URL パラメータ（または x-goog-quota-user HTTP ヘッダー）を使用して、課金対象のユーザーを指定します。これは割り当ての計算にのみ使用されます。詳細については、Cloud ドキュメントのユーザーあたりのリクエスト数の制限をご覧ください。
割り当て上限の処理をテストする
アプリケーションが実際に割り当て上限に達した場合に適切に処理できるように（指数バックオフで再試行を行うなど）、またユーザーへの潜在的な影響を最小限に抑えるために、このシナリオを実際の環境でテストすることを強くおすすめします。
このようなテストが実際のアプリケーションの使用に影響しないようにするには、Google API Console でテスト専用のプロジェクトを別途登録し、本番環境のプロジェクトと同様の方法で構成することをおすすめします。次に、このプロジェクトに人為的に低い割り当てを設定し、アプリケーションの動作を観察します。
料金
Google Calendar API はすべて追加料金なしでご利用いただけます。割り当てリクエストの上限を超えても、追加料金は発生せず、アカウントに請求されることもありません。