Google Workspace API の基本設計思想とは？

Google Workspace（Gmail / Drive / Calendar / Chat / Admin SDK など）のAPI群は、表層は一般的によくあるREST APIで統一されていますが、背後にある前提は「グローバル分散システム」です。Googleはプロダクトによっては数十億のユーザーがいると言われており、この莫大なユーザー操作を処理することを前提にシステムを構築しています。

この前提を理解することがGoogle Workspace APIを理解する上でとても重要です。今回は、分散システムをベースに構築されるGoogle Workspace APIの設計思想について説明します。

プロダクト主語のリソース設計

Drive の files、Calendar の events、Gmail の threads/messages、Chat の spaces/messages のように、ユーザーが日常で触る概念がAPI のリソースになるように設計されています。エンドポイントは REST/JSON（内部では gRPC/Protocol Buffers 起源）で、フィールドはスキーマ化・型付けされ、部分更新（update＋fieldMask）や部分応答（fields=…）で帯域と整合性コストを制御できるようになっています。

認証・認可は最小権限に抑えることができる

OAuth 2.0 のスコープは細かく分割されており、開発者はユーザー同意とドメインワイド委任（Admin 管理下）を使い分けることができます。ドメインワイド委任は、最初の初期設定を実施できれば、システムから権限の範囲でユーザー権限を使ったAPI実行が可能になります。ただし、APIの権限範囲を広げれば広げるほど、利用側のリスクは上がるため、「必要最小限しか権限を取らない」ことは常に意識しましょう。

大規模分散システムの可用性担保のためのクオータ制限

Google 側はマルチテナント・超大規模運用なので、レート制限（429）や日次クオータが仕様として定義されています。クライアントはAPIを使った実装を行う場合、指数バックオフを利用して、レート制限への対策を実施する必要があります。ただし、全てのエラーで指数バックオフを使うことはシステム全体のパフォーマンスを落とすことになるので、「リトライが必要なエラー」のみを識別して、指数バックオフを取り入れるようにしましょう。

※ 指数バックオフについては、コチラの記事をご参考ください。

データの一貫性に対する考え方

Google Cloud には強整合ストア（Cloud Spanner）も存在しますが、Google Wrokspace APIでは結果整合性が採用されています。直後の GET で反映遅延が起きたり、インデックス更新が後続したり、別リージョンからの読み取りで遅延が見えたり、更新までにラグが発生することを前提にAPIは提供されています。

「ACID は弱い？」への実務的な解像度

トランザクション境界は API 呼び出し単位です。複数リソースの同時更新や二相コミットは原則ありません。読取直後の整合性は保証されないことがあります。Drive の検索や Gmail のスレッド一覧で「さっき作ったのに出ない」現象は分散インデックス更新の宿命です。ただし、GoogleのAPIでは競合検出・差分同期のオプション（ETag、syncToken、historyId、pageToken など）が用意されているため、アプリ側では「いつか一致する」という実装が可能です。つまり、Googleは「ACID を弱めた」のではなく、システムの可用性を優先し、そのトレードオフをクライアント側で補う設計にしたということだと思います。

API 横断で共通する分散前提の作法

冪等性の考え方

APIは再試行前提で構築されています。また、POST/PUT/PATCH はクライアント生成の requestId（Sheets/Chat/Tasks 等で存在）や自然キーで二重作成を防ぐことも検討が必要です。

API実行時にAPIからステータスコードとして、クオータ制限を意味する429や5xxが返ってきた場合は、落ち着いて指数バックオフを実行してください。さらに最大試行回数・全体タイムアウト・観測ログを必ず実装に組み込むようにしてください。

一覧は常にページング

すべての list 系のAPIは pageToken と pageSize オプションを使うことが基本になります。並列化しすぎない・順序不問で設計・欠落分は差分同期で拾うというのが鉄則になります。

スループットと帯域の節約

Google Workspace APIでは部分応答オプション（fields=…）を利用することができます。帯域の節約のために、必要なデータだけ取得するようにしましょう。

エラーの分類と監視

Google Workspace APIのエラー種別は多岐に渡ります。レスポンスのステータスコードとレスポンスに含まれるreasonの組み合わせによってエラーハンドリングを実施してください。クオータ制限に関連する、もしくは500系のエラーの場合は指数バックオフによって、リトライ処理を実施することを検討してください。ただし、例えば400エラーといったクライアント側に起因するようなエラーの場合は、あくまで実装側の問題であるため、リトライするのは適切ではありません。

※ Google ドライブ APIのエラー解決方法はコチラのページをご参考ください。

まとめ

Googleのプロダクトは最大数十億のユーザーに利用されていると言われています。それが前提の上で、Google Workspaceは構築されており、APIもその条件の上で構築されています。Google Workspace APIは強いACIDは保証されていませんが、その問題を解決するためのオプションが豊富に用意されています。ユーザーはこれらのオプションを活用し、冪等・差分・エラーハンドリングを設計初期から織り込み、ユーザー体験が損なわれない実装を心がける必要があります。