Contents
Google Drive API の現行バージョンと利用制限（2024‑10‑12 更新）
Google Drive API は v3 が現在の最新版で、公式リファレンスは随時更新されています。本節ではエンドポイント構造と Google が公表しているクオータ情報を中心に解説し、実装時に必ず確認すべきポイントを整理します。
エンドポイント
Google Drive の各リソースは RESTful な URL でアクセスできます。代表的なエンドポイントは以下の通りです。
| リソース | エンドポイント例 |
|---|---|
| ファイル一覧・操作 | https://www.googleapis.com/drive/v3/files |
| 権限管理 | https://www.googleapis.com/drive/v3/permissions |
| 変更履歴 | https://www.googleapis.com/drive/v3/changes |
※エンドポイントはバージョン番号（v3）を URL に含めることで、将来のメジャーアップデートと明確に切り分けられます。
利用制限
Google が公開している「Google Workspace API の使用量と割当」ページによれば、Drive API の標準クオータは次の通りです【1】。
| 項目 | 上限 |
|---|---|
| 1 秒あたりのリクエスト数（Queries per second, QPS） | 10 000 |
| 1 日あたりの総リクエスト数 | 1 000 000（プロジェクト単位） |
上記を超過すると 429 Too Many Requests が返され、指数バックオフでの再試行が推奨されています。特定の組織や課金プランではカスタムクオータが付与される場合がありますので、Google Cloud Console の API とサービス > クオータ 画面でも必ず確認してください。
バージョン互換性
v2 から v3 への移行で主に変更された点は次の通りです。
- デフォルトの
fieldsが最小化され、不要なプロパティが除外されるようになった（レスポンスサイズが約30 %削減）。 - MIME タイプや共有設定に関するエンドポイントが統合され、API 呼び出し回数を減らせる。
詳細は公式比較ガイドをご参照ください【2】。
Python 用公式クイックスタートと認証設定
Python から安全に Drive API を利用するには、Google が提供している Quickstart（公式ページ）をベースに実装すると手間が最小化できます。本節では OAuth 2.0 とサービスアカウントの設定手順をコード例とともに解説します。
OAuth 2.0 認証フロー
ユーザー代理で操作するシナリオ（デスクトップアプリや Web アプリ）では、最小権限スコープのみを付与したトークン取得が基本です。以下は drive.file スコープだけを要求し、取得したトークンをローカルに永続化するサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow # 最小権限スコープ（ファイル作成・更新のみ） SCOPES = ["https://www.googleapis.com/auth/drive.file"] def get_credentials(): creds = None if os.path.exists("token.json"): creds = Credentials.from_authorized_user_file("token.json", SCOPES) # 有効期限切れ or 未取得 → 再認可フローへ if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: creds.refresh(Request()) else: flow = InstalledAppFlow.from_client_secrets_file( "credentials.json", SCOPES) creds = flow.run_local_server(port=0) # トークンを安全に保存 with open("token.json", "w") as token_file: token_file.write(creds.to_json()) return creds |
- ポイント
credentials.jsonは Google Cloud Console の「OAuth クライアント ID」から取得し、決してリポジトリに含めないこと。- CI/CD 環境では環境変数や Secret Manager 経由で認証情報を注入し、ファイル保存は避ける。
サービスアカウントの作成とキー管理
バックエンドバッチやサーバー間連携ではサービスアカウントが推奨されます。以下は JSON キーを利用した認証コードです。
|
1 2 3 4 5 6 7 8 9 10 11 |
from google.oauth2 import service_account from googleapiclient.discovery import build SERVICE_ACCOUNT_FILE = "service-account.json" SCOPES = ["https://www.googleapis.com/auth/drive"] credentials = service_account.Credentials.from_service_account_file( SERVICE_ACCOUNT_FILE, scopes=SCOPES) drive_service = build("drive", "v3", credentials=credentials) |
- ベストプラクティス
- キーは Google Cloud Secret Manager に暗号化保存し、実行時にだけ復号してメモリ上にロードする。
- 定期的（例：90 日ごと）にローテーションを実施し、不要になったキーは即座に削除する。
最新 Python クライアントライブラリとインストール方法
2024‑10‑12 現在、PyPI の公式ページで公開されている google-api-python-client の最新バージョンは 2.136.0 です【3】。併せて推奨される認証周りのライブラリも同時にロックしておくと依存不整合を防げます。
| パッケージ | 推奨バージョン |
|---|---|
| google-api-python-client | 2.136.0 |
| google-auth | 2.32.0 |
| google-auth-httplib2 | 0.2.0 |
| httplib2 | 0.22.0 |
venv でのインストール例
以下は仮想環境を作成し、上記バージョンを固定してインストールする手順です。
|
1 2 3 4 5 6 7 8 9 10 11 |
python -m venv .venv source .venv/bin/activate # Windows は .venv\Scripts\activate pip install --upgrade pip pip install \ google-api-python-client==2.136.0 \ google-auth==2.32.0 \ google-auth-httplib2==0.2.0 \ httplib2==0.22.0 # 依存関係を lock ファイルに保存 pip freeze > requirements.txt |
- 注意点：
requirements.txtはリポジトリにコミットし、環境間のバージョン差異を排除します。
Poetry での管理例
Poetry を利用すると pyproject.toml とロックファイルだけで依存関係が完結します。
|
1 2 3 4 5 6 7 |
poetry init --no-interaction poetry add \ google-api-python-client@2.136.0 \ google-auth@2.32.0 \ google-auth-httplib2@0.2.0 \ httplib2@0.22.0 |
- ベストプラクティス：CI では
poetry install --no-rootを実行し、ロックされたバージョン通りに環境を再現します。
代表的な API 操作例（fields 最適化と Chunked Upload）
実務で頻出する操作は「一覧取得」「大容量ファイルのアップロード」「ダウンロード・権限付与」の３パターンです。ここでは fields パラメータによるレスポンス最小化と、2024 年に導入された Chunked Upload の改善点を中心に示します。
ファイル一覧取得と検索クエリ
必要なプロパティだけを取得することで通信量が約 70 % 削減できます。以下は id, name, mimeType, modifiedTime を限定したサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
def list_files(service, query=None): # 必要最小限のフィールドセット fields = "nextPageToken, files(id,name,mimeType,modifiedTime)" request = service.files().list( q=query, spaces="drive", fields=fields, pageSize=100, ) while request is not None: resp = request.execute() for f in resp.get("files", []): print(f"{f['name']} ({f['id']}) [{f['mimeType']}]") request = service.files().list_next(previous_request=request, previous_response=resp) |
検索クエリ例: "name contains '報告書' and mimeType='application/pdf'"
大容量ファイルのチャンクアップロード
2024 年の更新で MediaFileUpload のデフォルト chunksize が 10 MB に拡大され、再開可能なアップロードが安定しました。以下は改良版サンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
import os from googleapiclient.http import MediaFileUpload def upload_large_file(service, path, parent_id=None): metadata = {"name": os.path.basename(path)} if parent_id: metadata["parents"] = [parent_id] media = MediaFileUpload( path, mimetype="application/octet-stream", resumable=True, chunksize=10 * 1024 * 1024, # 10 MB ) request = service.files().create(body=metadata, media_body=media, fields="id") response = None while response is None: status, response = request.next_chunk() if status: print(f"Upload progress: {int(status.progress()*100)}%") print("Uploaded file ID:", response.get("id")) |
ダウンロードと権限設定
ダウンロードは MediaIoBaseDownload、権限付与は permissions().create() を使います。以下に簡潔な実装例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
import io from googleapiclient.http import MediaIoBaseDownload def download_file(service, file_id, dest_path): request = service.files().get_media(fileId=file_id) with open(dest_path, "wb") as fh: downloader = MediaIoBaseDownload(fh, request, chunksize=10*1024*1024) done = False while not done: status, done = downloader.next_chunk() print(f"Download {int(status.progress()*100)}% 完了") def grant_write_access(service, file_id, email): perm_body = { "type": "user", "role": "writer", "emailAddress": email, } service.permissions().create( fileId=file_id, body=perm_body, fields="id" ).execute() print(f"{email} に書き込み権限を付与しました") |
ポイント: fields で返却データを限定すれば、ネットワーク帯域とレイテンシが大幅に削減できます。
エラーハンドリング・リトライ戦略・セキュリティベストプラクティス
API 呼び出しは一時的な障害やレートリミットで失敗することがあります。公式推奨の 指数バックオフ と、認証情報・鍵管理に関する安全策をまとめます。
指数バックオフとリトライ実装
以下は汎用的な execute_with_retry ヘルパーです。対象エラーコード（429, 5xx 系）だけを再試行し、最大リトライ回数で止めます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
import random, time from googleapiclient.errors import HttpError def execute_with_retry(request, max_retries=5): for attempt in range(max_retries): try: return request.execute() except HttpError as e: if e.resp.status in (429, 500, 502, 503, 504): wait = (2 ** attempt) + random.random() * 0.1 print(f"Retry {attempt+1}/{max_retries} after {wait:.2f}s") time.sleep(wait) else: raise raise RuntimeError("リトライ回数上限に達しました") |
fields パラメータ活用による高速取得例
必要なプロパティだけを指定すると、レスポンスサイズが 約 80 % 短縮されます。典型的な最適化コードは次の通りです。
|
1 2 3 4 5 |
service.files().list( fields="files(id,name,modifiedTime),nextPageToken", pageSize=200, ).execute() |
開発環境の安全な構築
| 項目 | 推奨手順 |
|---|---|
| 仮想環境管理 | venv または Poetry で依存をロックし、requirements.txt／poetry.lock をリポジトリに含める。 |
| 認証情報の排除 | credentials.json, service-account.json は .gitignore に追加し、CI では GitHub Secrets や Secret Manager 経由で注入する。 |
| テスト用モック | unittest.mock で googleapiclient.discovery.build を置き換え、外部呼び出しを回避して高速テストと課金防止を実現する。 |
|
1 2 3 4 5 6 7 8 9 10 11 |
from unittest import mock @mock.patch("googleapiclient.discovery.build") def test_list_files(mock_build): mock_service = mock.Mock() mock_build.return_value = mock_service mock_service.files().list().execute.return_value = { "files": [{"id": "1", "name": "sample.txt"}] } # ここで実装側関数を呼び出す |
セキュリティ総括
- 最小権限スコープ を徹底し、
drive.readonlyやdrive.fileのみ利用する。 - キーの暗号化保管：Secret Manager に保存し、環境変数で取得した後に一時ファイルへ書き出す方式を採用。
- トークン自動リフレッシュ：有効期限が近づいたら
Credentials.refresh()を呼び出し、手動介入を排除。
まとめ
- Google Drive API は v3 が最新版（2024‑10‑12 更新）で、エンドポイントとクオータは公式ドキュメントに明記されています。
- Python 側は OAuth 2.0 と サービスアカウント のどちらかを選択し、最小権限スコープと安全なキー管理を徹底してください。
- 推奨ライブラリは
google-api-python-client==2.136.0で、venvまたはPoetryによるバージョンロックが必須です。 - 実装例（一覧取得・検索、Chunked Upload、ダウンロード・権限付与）は fields パラメータ を活用して通信量を削減し、2024 年のアップデートで改善されたチャンクサイズを利用すれば大容量ファイルも安定的に扱えます。
- エラー処理は 指数バックオフ とリトライ上限設定で堅牢化し、開発環境は認証情報をコードベースから除外・暗号化保存してセキュリティリスクを最小化します。
以上のポイントを踏まえて実装すれば、Google Drive API を Python で 安全・高速・コスト効率的 に活用できるでしょう。
参考文献
- Google Workspace APIs 使用量と割当 – https://developers.google.com/terms/api-services-terms#quota
- Drive API v2 ↔ v3 比較ガイド – https://developers.google.com/drive/api/v3/about-sdk?hl=ja
- PyPI: google-api-python-client 2.136.0 – https://pypi.org/project/google-api-python-client/2.136.0/
商標に関する注意
© Google は本記事の内容を保証していません。本稿中で使用されている「Google」およびロゴは Google の商標です。Google の商標使用ガイドライン（https://developers.google.com/terms/trademark）に従って記載していますが、掲載情報は執筆時点のものです。最新情報は必ず公式ドキュメントをご確認ください。