割り当てを管理

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

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

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

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

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

割り当ては、スライディングウィンドウを使用して 1 分ごとに計算されます。そのため、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 回ポーリングする場合、作業を行う前に 1 分あたり少なくとも 5,000 の割り当てが必要になります。

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

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

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

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

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

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

料金

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

割り当てを管理 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。