Google Drive APIは、Googleドライブ上のファイルやフォルダ、共有設定をHTTPのREST呼び出しで操作するためのAPIです。基幹システムが作った帳票PDFを共有ドライブへ自動で保存する、特定フォルダの新着ファイルを拾って処理する、取引先ごとのフォルダに閲覧権限を付けるといった連携に使います。この記事では、現行のv3を対象に、OAuthスコープとサービスアカウントの選び方、Pythonでのアップロード・検索・共有のコード、エラーとクォータの扱いまでを、2026年11月時点の公式ドキュメントに沿って説明します。
まとめ:Google Drive APIでアップロード・検索・共有を組むときに押さえる要点
- 認証:サービスアカウントは自分の保存容量を持たず、ファイルを所有できない。保存先は共有ドライブにするか、ドメイン全体の委任で社員になり代わる。
- スコープ:アプリが作ったファイルだけを扱うなら非機密の
drive.fileで足りる。既存ファイルを読むなら制限付きのdriveかdrive.readonlyが要る。 - 共有ドライブ:
files.createやfiles.listにsupportsAllDrives=Trueを付け忘れると、共有ドライブのファイルが見えず404になる。 - アップロード:5MB以下ならmultipart、それを超えるか回線が不安定なら再開可能(resumable)を使う。
- 検索:
qパラメータでフォルダ・種類・更新日時を絞り、pageSizeは最大1,000件、続きはnextPageTokenで取る。 - 上限:2026年5月1日以降に作ったプロジェクトは、1分あたりプロジェクト100万・ユーザー32万5,000のクォータ単位で数え、一覧取得は1回100単位を消費する。
Google Drive API v3の用途と2026年5月以降のクォータ単位・課金の前提
Drive APIで扱う対象は、ファイル本体とメタデータ、共有設定、共有ドライブ、変更履歴です。業務システムとの連携で毎回使うのは、ファイルとフォルダを作成・検索するfilesと、共有設定を変えるpermissionsの2つです。
業務連携の大半を担う4リソースの用途別構成と主な操作メソッド
DriveではフォルダもmimeTypeがフォルダ用の値になった「ファイル」の一種として扱われ、ファイルがどのフォルダに入るかはparentsに親フォルダのIDを入れて決めます。パスの文字列でファイルを指定する仕組みは無いので、連携では最初に保存先フォルダのIDを控えておきます。
| リソース | 主なメソッド | 業務連携での用途 |
|---|---|---|
| files | 作成・一覧・取得・更新・コピー | 帳票の保存、新着ファイルの検索、ダウンロード |
| permissions | create・list・delete | 取引先や社員への閲覧・編集権限の付与と取り消し |
| drives | create・list | 共有ドライブの作成と一覧(管理者向け) |
| changes | 開始トークン取得・一覧・監視 | 前回以降に変わったファイルの差分取得 |
表の4リソースのうち、filesの作成・一覧・取得・更新・コピーに対応するメソッドは順にcreate・list・get・update・copyです。changesの開始トークン取得・一覧・監視には順にgetStartPageToken・list・watchを使います。
新着ファイルの検知をfiles.listの定期実行で済ませるかchangesで差分を取るかは、対象フォルダのファイル数で決めます。数千件までなら更新日時で絞った一覧取得で十分です。
メソッドごとのクォータ消費量と1分あたりの上限から逆算する呼び出し回数
Drive APIの利用上限のページによると、2026年5月1日以降に作成したGoogle Cloudプロジェクトには新しいクォータが適用され、2025年11月〜2026年4月に利用実績のあるプロジェクトは従来の上限が続きます。新しいクォータは呼び出し回数ではなく「クォータ単位」で数え、1分あたりプロジェクト全体で1,000,000単位、プロジェクト内のユーザーごとに325,000単位が上限です。
消費量はメソッドの種類で決まり、読み取り(get)が5、一覧(list)が100、作成・更新・削除が50、ダウンロードが200単位です。1人のユーザーで一覧取得だけを繰り返すと、325,000÷100で1分あたり約3,250回が天井になります。1日の転送量はダウンロードでプロジェクトあたり1TB、Workspaceユーザーのアップロードとコピーは1日750GBまでです。
料金は、標準的な利用には追加費用がかからないと案内されています。一方、1日あたりプロジェクト4億単位の課金しきい値を超えた分は2026年後半から課金を始める予定で、詳細は少なくとも90日前に通知するとされています。大量のファイルを毎日処理するバッチは、今のうちに1日の消費単位を見積もっておくと安心です。
認証方式の選び方:OAuthスコープの機密区分とサービスアカウント・共有ドライブ
Drive APIでつまずく原因の多くは、コードではなく認証の組み立てにあります。スコープと、誰の権限でファイルを触るかを先に決めます。
drive.fileと制限付きスコープdriveの違いとセキュリティ評価が要る条件
Drive APIのスコープの選び方では、スコープが機密性で3段階に分けられています。
| スコープ | 区分 | 扱える範囲 |
|---|---|---|
| drive.file | 非機密 | アプリ作成または利用者がアプリで開いたファイル |
| drive.appdata | 非機密 | アプリ専用の隠しフォルダ |
| drive.readonly | 制限付き | ドライブ全体の読み取り |
| drive.metadata.readonly | 制限付き | ファイルのメタデータの読み取り |
| drive | 制限付き | ドライブ全体の読み書き |
制限付きスコープのデータをサーバーに保存したり送信したりする場合は、セキュリティ評価を受ける必要があると明記されています。社外の利用者に公開するアプリで「全ファイルを読める」権限を求めると審査の負担が大きくなるため、システムが自分で作った帳票を保存して読み返すだけの連携ならdrive.fileにとどめます。社内のWorkspaceだけで使う内部アプリは公開アプリの審査対象になりませんが、権限を必要最小限にする考え方は同じです。スコープと認可の仕組みはOAuth 2.0の仕組みと認可フローで詳しく説明しています。
容量を持たないサービスアカウントは共有ドライブかドメイン全体の委任で使う
夜間バッチのように人が操作しない処理では、サービスアカウントを使う構成です。ただし共有ドライブの概要には、サービスアカウントは保存容量を持たず、ファイルを所有できないと書かれています。サービスアカウントのマイドライブにアップロードしようとすると、403のstorageQuotaExceededで失敗します。
回避策は2つです。1つは、共有ドライブを作ってサービスアカウントのメールアドレスをメンバーに加え、そこへ保存する方法です。共有ドライブのファイルは組織が所有するので、容量の問題が起きません。もう1つは、サーバー間認証のガイドにあるドメイン全体の委任を設定し、サービスアカウントが特定の社員になり代わって、その社員のマイドライブを操作する方法です。委任は組織内の全ユーザーのデータに届く強い権限なので、Workspaceの管理者が許可するスコープを絞って登録します。新しく作る連携なら、権限の範囲を共有ドライブ1つに閉じ込められる前者を選んでください。
共有ドライブは1つあたり、ごみ箱内も含めて最大500,000アイテムまで、フォルダの階層は100段までです。また共有ドライブにはownerロールが無く、管理者・コンテンツ管理者・投稿者などのロールで権限を分けます。
検証環境の準備:API有効化・サービスアカウント鍵の作成と共有ドライブへの追加
Google Cloudのプロジェクトで、APIの有効化からサービスアカウントの鍵作成までを行います。Python向けのクイックスタートはOAuthのユーザー認可で説明していますが、ここではバッチ向けにサービスアカウントで組みます。
# ライブラリのインストール
pip install --upgrade google-api-python-client google-auth
# Drive APIの有効化とサービスアカウントの作成(gcloud CLI)
gcloud services enable drive.googleapis.com
gcloud iam service-accounts create drive-batch --display-name="Drive連携バッチ"
gcloud iam service-accounts keys create sa-key.json \
--iam-account=drive-batch@YOUR_PROJECT_ID.iam.gserviceaccount.com
組織のポリシーでサービスアカウント鍵の作成が禁止されている場合は、鍵ファイルを使わずにCloud RunなどGoogle Cloud上の実行環境に割り当てたサービスアカウントの認証情報を使います。鍵ファイルを作った場合は、リポジトリに含めず、シークレット管理の仕組みに置いてください。
次に、Googleドライブの画面で保存先の共有ドライブを開き、「メンバーを管理」からdrive-batch@…iam.gserviceaccount.comをコンテンツ管理者として追加します。管理コンソールで共有ドライブへの組織外メンバーの追加を制限していると、サービスアカウントを追加できない場合があるので、その際は管理者に設定を確認してもらいます。保存先フォルダのIDは、ブラウザでフォルダを開いたときのURLの末尾の文字列です。
Pythonで共有ドライブへファイルをアップロードする再開可能アップロードのコード
帳票PDFを共有ドライブのフォルダへ保存するコードです。MediaFileUploadにresumable=Trueを付けると再開可能アップロードになります。
from google.oauth2 import service_account
from googleapiclient.discovery import build
from googleapiclient.http import MediaFileUpload
SCOPES = ["https://www.googleapis.com/auth/drive"]
creds = service_account.Credentials.from_service_account_file("sa-key.json", scopes=SCOPES)
drive = build("drive", "v3", credentials=creds)
FOLDER_ID = "共有ドライブ内の保存先フォルダID"
def upload_pdf(local_path, name):
meta = {"name": name, "parents": [FOLDER_ID]}
media = MediaFileUpload(local_path, mimetype="application/pdf", resumable=True)
f = drive.files().create(
body=meta,
media_body=media,
fields="id, name, webViewLink",
supportsAllDrives=True, # 共有ドライブに保存するときは必須
).execute(num_retries=5)
return f
f = upload_pdf("invoice_202611.pdf", "請求書_2026-11_株式会社サンプル.pdf")
print(f["id"], f["webViewLink"])
サービスアカウントが自分で作ったファイルだけを扱うなら、SCOPESをdrive.fileに変えても動きます。共有ドライブに人が置いた既存のファイルも読む処理を同じプログラムに入れるなら、driveのままにします。
uploadTypeの3方式と5MBを境にした選択基準、共有ドライブ指定漏れ
ファイルのアップロードのガイドでは、送信先のuploadTypeとして3つの方式が示されています。
| uploadType | 送れるもの | 向いている場面 |
|---|---|---|
| media | ファイル本体のみ | 5MB以下でメタデータが不要 |
| multipart | 本体とメタデータを1回で | 5MB以下で名前や保存先を指定する |
| resumable | 本体とメタデータを分割して | 5MB超、または通信が切れやすい |
再開可能アップロードは小さいファイルにも使え、追加のHTTPリクエストは1回だけです。サイズで分岐を書くより、業務連携では常にresumable=Trueにしておくほうが、途中で失敗したときの扱いが揃います。
もう一つの落とし穴がsupportsAllDrivesです。共有ドライブ対応の実装ガイドは、このパラメータでアプリが共有ドライブのファイルを扱えることをDriveに伝えると説明する仕様です。付け忘れると、保存先フォルダが共有ドライブにある場合に親フォルダが見つからず、404のnotFoundが返ります。files.create・files.get・files.update・permissions.createのすべてに付けておきます。
files.listのqによるフォルダ内・更新日時・ファイル名検索とページング
共有ドライブの特定フォルダから、指定日時より後に更新されたPDFを新しい順に取り出すコードです。前の章で作ったdriveをそのまま使います。
def list_new_pdfs(drive_id, folder_id, since_utc):
# since_utc の例: "2026-11-20T00:00:00"(タイムゾーン未指定はUTCとして扱われる)
q = (
f"'{folder_id}' in parents and trashed = false "
f"and mimeType = 'application/pdf' and modifiedTime > '{since_utc}'"
)
token = None
while True:
res = drive.files().list(
q=q,
corpora="drive",
driveId=drive_id,
includeItemsFromAllDrives=True,
supportsAllDrives=True,
pageSize=1000,
orderBy="modifiedTime desc",
fields="nextPageToken, files(id, name, modifiedTime, size)",
pageToken=token,
).execute(num_retries=5)
yield from res.get("files", [])
token = res.get("nextPageToken")
if not token:
break
for f in list_new_pdfs("共有ドライブID", "フォルダID", "2026-11-20T00:00:00"):
print(f["modifiedTime"], f["name"])
ファイル検索のガイドによると、qは「検索対象の項目・演算子・値」の組み合わせで書き、name contains 'budget'のような部分一致やfullText containsによる本文検索も使えます。名前にアポストロフィを含む場合はバックスラッシュでエスケープします。nextPageTokenが返らなくなった時点で結果は終わりです。
files.listのリファレンスでは、pageSizeの上限は1,000で、それを超える値は1,000に丸められる仕様です。並び順は大量のファイルでcreatedTimeを使うとタイムアウトの原因になりうるため、modifiedTime descが推奨される並び順です。corporaは既定がuserで、共有ドライブ1つに絞るならdriveとdriveIdを指定します。複数の共有ドライブを横断するallDrivesは、検索しきれなかったドライブがあると結果の一部が欠けたことを示す値が返る場合があるため、件数の多い検索では避けます。
permissions.createによる社内ファイル共有と通知メールの抑制設定
アップロードしたファイルを担当者や取引先に見せるには、permissions.createで権限を付けます。ファイルの共有のガイドにあるtype(user・group・domain・anyone)とrole(reader・commenter・writerなど)の組み合わせで指定します。
def share_with(file_id, email, role="reader"):
return drive.permissions().create(
fileId=file_id,
body={"type": "user", "role": role, "emailAddress": email},
sendNotificationEmail=False, # 一括処理では通知メールを止める
supportsAllDrives=True,
fields="id",
).execute(num_retries=5)
share_with(f["id"], "[email protected]")
数百件のファイルに機械的に権限を付ける処理で通知メールを送ると、受け取る側の受信箱が埋まります。共有の事実はシステム側の画面やチャットで知らせ、sendNotificationEmail=Falseにしておくのが無難です。取引先ごとにファイルを分けて共有するなら、ファイル単位ではなく取引先ごとのフォルダに権限を付け、その中に保存する形にすると、権限の付与と棚卸しの回数が減ります。社内の閲覧範囲をドライブの権限で設計する考え方はGoogleサイトで社内ポータルを作る手順とドライブ権限の設計でも扱っています。
403・404・429エラーの原因と指数バックオフによる再試行の実装方法
Drive APIのエラー対処のガイドから、連携で遭遇しやすいものを原因別に整理します。
| コード | reason | 主な原因と対処 |
|---|---|---|
| 401 | authError | トークン切れ・スコープ不足。認証情報を作り直す |
| 403 | storageQuotaExceeded | サービスアカウントの保存先を共有ドライブへ |
| 403 | ファイル権限不足 | 書き込み権限が無い。共有ドライブのロールを確認 |
| 403 | userRateLimitExceeded | ユーザー単位の上限超過。間隔を空けて再試行 |
| 404 | notFound | ID誤り・読み取り権限なし・共有ドライブ指定漏れ |
| 429 | rateLimitExceeded | 短時間の送りすぎ。指数バックオフで再試行 |
| 5xx | — | サーバー側の一時的な障害。指数バックオフで再試行 |
サービスアカウントのマイドライブへ保存するとstorageQuotaExceededが発生します。表のファイル権限不足はinsufficientFilePermissionsを指します。また、404の共有ドライブ指定漏れはsupportsAllDrivesの付け忘れです。
ここまでのコードでexecute(num_retries=5)としているのは、Pythonのクライアントライブラリが持つ再試行の仕組みを使うためです。429や5xx、レート超過の403を受けると、待ち時間を伸ばしながら最大5回まで自動で送り直します。権限不足やnotFoundは何度送っても結果が変わらないので、再試行に任せず、ログに出して処理を止めます。
大量のファイルを並列で処理するときは、スレッド数を増やす前に、1分あたりのクォータ単位を上の章の消費量で見積もります。一覧取得を毎分回すより、前回取得した時刻以降の更新分だけをmodifiedTimeで取るほうが、消費単位を抑えられます。
Drive API連携を自社で組むか、iPaaSやGASで済ませるかの判断基準
Googleドライブとの連携は、Drive APIを直接呼ぶ以外にも手段があります。要件の規模で選び分けます。
フォームの添付ファイルを決まったフォルダに保存する、新着ファイルをチャットに通知するといった単発の処理は、ZapierやMakeなどのiPaaSで足ります。Workspaceの中で完結し、1日に数十件程度を扱うなら、Google Apps ScriptのDriveAppでも十分です。GASは実行時間などの上限があるため、上限の数値はGAS(Google Apps Script)のできることと制限の数値で確かめてから選んでください。
Drive APIを自社のプログラムで呼ぶべきなのは、基幹システムや販売管理システムの帳票を毎日数百件以上保存する、取引先ごとのフォルダ権限をシステムのマスタと同期させる、誰がいつどのファイルを共有したかを監査用に記録する、といった要件があるときです。この場合はiPaaSの実行回数の課金やGASの実行時間の上限が先に問題になり、再試行と権限の設計を自分で持てるほうが運用が安定します。反対に、扱うファイルが月に数十件で、権限も固定のフォルダ1つで済むなら、自社開発は過剰です。
同じGoogle Workspaceの連携でも、表の読み書きはGoogle Sheets APIの使い方、予定の作成はGoogle Calendar APIの使い方で、認証の組み立て方をそろえて解説しています。社内システムとGoogle Workspaceをつなぐ設計や、既存システムからのファイル連携の実装は、一創のAPI開発・システム連携でご相談いただけます。
よくある質問
Google Drive APIを使い始めるときによく出る疑問に答えます。
Google Drive APIは無料で使えますか?
標準的な利用には追加費用がかからないと公式に案内されています。ただし2026年5月1日以降に作成したプロジェクトでは、1日あたりプロジェクト4億クォータ単位を超えた分について、2026年後半から課金を始める予定とされています。課金の詳細は少なくとも90日前に通知されるため、大量処理をするバッチは利用上限のページを定期的に確認してください。
個人のGoogleアカウントでサービスアカウントから共有ドライブを使えますか?
共有ドライブはGoogle Workspaceの機能なので、個人の無料アカウントでは作れません。個人アカウントでサービスアカウントを使う場合、サービスアカウントは保存容量を持たないため、ファイルの保存先にできません。個人のドライブを扱うなら、OAuthのユーザー認可で本人の権限としてAPIを呼びます。
ファイルをダウンロードするにはどうすればよいですか?
通常のファイルはfiles.getにalt=mediaを指定して本体を取得し、Pythonではfiles().get_media()とMediaIoBaseDownloadを組み合わせる形です。GoogleドキュメントやスプレッドシートのようなGoogle形式のファイルは本体を持たないため、files.exportでPDFやExcel形式に変換して取得します。ダウンロードは1回で200クォータ単位を消費します。
APIで作ったファイルがドライブの画面に表示されないのはなぜですか?
サービスアカウントがマイドライブ側に作ったファイルは、サービスアカウント自身のものになるため、人の画面には出てきません。現在は容量の制約で保存自体が失敗することが多いので、共有ドライブのフォルダIDをparentsに指定して保存し直します。共有ドライブに保存したのに見えない場合は、閲覧する人がその共有ドライブのメンバーかを確認してください。
Google Apps ScriptのDriveAppとDrive APIはどちらを使うべきですか?
Workspaceの中で完結する小規模な自動化ならDriveAppが手軽で、認証の準備も要りません。外部のシステムから呼ぶ、1日の処理件数が多い、再試行やログを自前で管理したいといった場合はDrive APIを使います。GASからもDrive APIの高度なサービスを呼べるので、DriveAppに無い操作だけをAPIで補う構成も取れます。
関連記事
- Google Sheets APIの使い方:サービスアカウント認証とPythonでの読み書き・batchUpdate:同じサービスアカウント構成で表を読み書きする実装
- Gmail APIの使い方:OAuthスコープの選び方とPythonでの送信・受信・ラベル操作、Pub/Sub通知:ドライブに保存したファイルの通知メールを送る連携
- Google Calendar APIの使い方|OAuth・サービスアカウント認証と予定作成・空き時間取得・プッシュ通知の実装例:ドメイン全体の委任の使い方を共通にした兄弟記事
- GAS(Google Apps Script)とは?できること・制限の数値・始め方とclasp 3での開発:小規模な自動化をGASで済ませる場合の上限
- OAuthとは?OAuth 2.0の仕組み・認証と認可の違いとOAuth 2.1の現状をわかりやすく解説:スコープと認可フローの基礎