割り当てを管理

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

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

Calendar API の使用量割り当ての種類

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

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

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

いずれかの割り当てを超過すると、レート制限され、クエリに対して 403 usageLimits ステータス コードまたは 429 usageLimits ステータス コードを受け取ります。この場合は、次の方法をお試しください。

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

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

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

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

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

リクエストのレートを遅くしたい場合は、403「usageLimits」レスポンスまたは 429 レスポンスが返されます(完全なエラードキュメントをご覧ください)。これは致命的なエラーではなく、短い間隔でリクエストを再試行してください。それでもリクエストが届くのが早すぎる場合は、再度リクエストします。これが正しく機能するには、リクエスト間の遅延が時間の経過とともに増加することが重要です。

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

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

カレンダー クライアントは、複数のクライアントが同時にオペレーションを実行するため、トラフィック パターンが急増しがちです。たとえば、カレンダー クライアントでは、真夜中に完全同期を実行することはよくありません。この場合、ほぼ間違いなく 1 分あたりの割り当てを超過し、レート制限とバックオフが発生します。

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

プッシュ通知を使用する

一般的なユースケースは、ユーザーのカレンダーに変更があったときにアクションを実行することです。この場合のアンチパターンは、対象となるすべてのカレンダーを繰り返しポーリングすることです。こうすれば、割り当てをすぐにすべて使い切ります。たとえば、アプリケーションのユーザー数が 5,000 人で、各ユーザーのカレンダーを 1 分に 1 回ポーリングする場合は、作業が完了する前であっても、1 分あたりの割り当てとして少なくとも 5,000 が必要になります。

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

サービス アカウントを使用した適切なアカウンティング

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

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

アプリケーションが割り当て上限への到達を適切に処理できるように(たとえば、指数バックオフを使用して再試行するなど)、ユーザーに対する潜在的な障害を最小限に抑えるために、このシナリオを実際の環境でテストすることを強くおすすめします。

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

料金

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