割り当てを管理

Google Calendar API には、すべてのユーザーが公平に使用できるようにするための割り当てがあります。Calendar API を使用する場合は、次の 3 つの重要な制限事項を考慮してください。

  • API 使用量の割り当ては、プロジェクトごととユーザーごとに適用されます。詳細については、次のセクションをご覧ください。
  • カレンダーの一般的な使用制限: カレンダーの使用制限を超えないようにします。
  • 運用上の制限: レート制限がいつでも適用される可能性があります。たとえば、1 つのカレンダーに連続して書き込もうとした場合です。

Calendar API 使用量の割り当てのタイプ

次の 2 種類の割り当てが適用されます。

  • プロジェクトあたり 1 分あたり: Google Cloud プロジェクトによって行われたリクエストの数です。
  • 1 プロジェクト、1 分、1 ユーザーあたり: Cloud プロジェクト内の特定のユーザーが行ったリクエストの数です。この上限は、ユーザー間で使用量を公平に分散することを目的としています。

割り当てはスライディング ウィンドウを使用して 1 分ごとに計算されるため、1 分間の分単位の割り当てを超えるトラフィックが急増すると、次のウィンドウでレート制限が行われ、平均使用量が割り当て内に収まるようにします。

いずれかの割り当てを超えると、レート制限が適用され、クエリに 403 usageLimits ステータス コードまたは 429 usageLimits ステータス コードが返されます。この場合は、次の対応を行ってください。

  1. 指数バックオフを使用する、トラフィック パターンをランダムにする、プッシュ通知を使用するなど、すべてのベスト プラクティスに従ってください。
  2. プロジェクトの規模が拡大し、ユーザー数が増えている場合は、プロジェクトごとの割り当ての増加をリクエストできます。
  3. ユーザーごとの割り当て上限に達した場合は、次のことができます。
    • サービス アカウントを使用する場合は、負荷をユーザーに割り当てるか、複数のサービス アカウント間で分割します。
    • ユーザーごとの割り当ての増加をリクエストすることはできますが、一般に、デフォルト値を超えて増やすことはおすすめしません。アプリケーションが他のタイプの上限（一般的なカレンダー使用の上限や運用上限など）に達する可能性があるためです。

割り当ての増加リクエスト

プロジェクトの使用量上限を確認して変更する手順、または割り当ての増加をリクエストする手順は次のとおりです。

  1. プロジェクトの請求先アカウントをまだ持っていない場合は、1 つ作成します。
  2. API Console で API ライブラリの [有効な API] ページに移動し、リストから API を選択します。
  3. 割り当て関連の設定を表示および変更するには、[割り当て] を選択します。使用統計情報を表示するには、[使用量] を選択します。

指数バックオフを使用する

リクエスト頻度を減らす必要がある場合は、403「usageLimits」レスポンスまたは 429 レスポンスが返されます（エラーに関する完全なドキュメントをご覧ください）。これは致命的なエラーではなく、しばらくしてからリクエストを再試行することをおすすめします。それでもリクエストが速すぎる場合は、再度リクエストをお願いすることになります。これが正しく機能するためには、リクエスト間の遅延が時間とともに増加することが重要です。

通常は、切り捨て型指数バックオフを使用する必要があります。Cloud Storage のドキュメントでは、この仕組みと推奨されるアルゴリズムについて詳しく説明しています。Google クライアント ライブラリを使用している場合は、通常はライブラリによって処理されます。ライブラリのドキュメントをご覧ください。通常は、独自に作成するのではなく、ライブラリの実装を使用する必要があります。

トラフィック パターンをランダム化する

カレンダー クライアントでは、複数のクライアントが同時にオペレーションを実行することにより、トラフィック パターンが急増する傾向があります。たとえば、カレンダー クライアントでよく見られる不適切な方法として、深夜に完全同期を行うことが挙げられます。これにより、ほぼ確実に 1 分あたりの割り当てを超え、レート制限とバックオフが発生します。

これを回避するには、可能な限りトラフィックが 1 日を通じて分散されるようにします。クライアントが毎日同期する必要がある場合は、クライアントにランダムな時刻（クライアントごとに異なる）を決定してもらいます。オペレーションを定期的に実行する必要がある場合は、間隔を +/- 25% 変動させます。これにより、トラフィックがより均等に分散され、ユーザー エクスペリエンスが大幅に向上します。

プッシュ通知を使用する

一般的なユースケースは、ユーザーのカレンダーで何かが変更されるたびにアクションを実行することです。アンチパターンは、関心のあるすべてのカレンダーを繰り返しポーリングすることです。これにより、割り当てが非常に早く使い切れます。たとえば、アプリケーションのユーザー数が 5,000 人で、各ユーザーのカレンダーを 1 分ごとにポーリングする場合、作業を開始する前に少なくとも 5,000 分の割り当てが必要になります。

サーバーサイド アプリケーションはプッシュ通知を登録できます。これにより、興味深い事象が発生したときに通知を受け取ることができます。これらの設定には手間がかかりますが、割り当てを大幅に効率的に使用でき、ユーザー エクスペリエンスが向上します。通知を受け取る eventType を指定してください。詳細については、プッシュ通知をご覧ください。

サービス アカウントの適切なアカウンティング

アプリケーションがドメイン全体の委任を使用してリクエストを実行している場合、デフォルトでは、権限を借用しているユーザーではなく、「ユーザーあたりのプロジェクトあたりの 1 分あたり」の割り当てに基づいてサービス アカウントに課金されます。つまり、サービス アカウントは複数のユーザーのカレンダーで動作している場合でも、割り当てが不足してレート制限を受ける可能性があります。これを回避するには、quotaUser URL パラメータ（または x-goog-quota-user HTTP ヘッダー）を使用して、請求先のユーザーを指定します。これは割り当ての計算にのみ使用されます。詳細については、Cloud のドキュメントのユーザーあたりのリクエスト数の制限をご覧ください。

割り当て上限の処理をテストする

実際の環境でこのシナリオをテストすることを強くおすすめします。これにより、アプリが割り当て上限に達した場合に、（指数バックオフで再試行するなど）適切に処理できるようになります。また、ユーザーへの影響を最小限に抑えることができます。

このようなテストが実際のアプリケーションの使用を妨げないようにするには、Google API Console でテスト専用のプロジェクトを別途登録し、本番環境プロジェクトと同様に構成することをおすすめします。その後、このプロジェクトに人為的に低い割り当てを設定して、アプリケーションの動作を観察できます。

料金

Google Calendar API はすべて追加料金なしでご利用いただけます。割り当てリクエストの上限を超えても、追加料金は発生せず、アカウントに請求されることはありません。