Contents
BigQuery Python API 接続の手順とサンプルコードを解説
BigQueryへのPython接続は、データ分析やETL処理において重要なスキルです。本記事では、Google Cloudプロジェクトの設定からOAuth2認証、クライアントライブラリのインストールまで、実際に導入できる手順と実行可能なコードサンプルをステップバイステップで解説します。
Google Cloudプロジェクトの初期設定
BigQueryにPythonからアクセスするには、まずGoogle Cloudプロジェクトの準備が必要です。プロジェクト作成とAPI有効化が前提となるため、以下のような手順で進めます。
プロジェクト作成とBigQuery APIの有効化
- Google Cloud Console（console.cloud.google.com）にアクセスし、「プロジェクトを作成」をクリックします。
- プロジェクト名を入力し、場所を選択して「作成」を実行します。
- 左メニューの「APIとサービス」→「ライブラリ」を開き、「BigQuery API」を検索し有効化します。
注意：API有効化後は、プロジェクトID（例:
my-project-123456）を控えておくことが重要です。このIDは認証処理やコード記述時に必要になります。
サービスアカウントの作成とJSON鍵ファイルの取得
BigQuery APIにアクセスするためには、サービスアカウントを作成し、その資格情報を管理します。
- Google Cloud Console → 「IAMと権限」→「サービスアカウント」を開きます。
- 「サービスアカウントを追加」→「サービスアカウントを作成」を選択します。
- 名前とメールアドレスを入力し、ロールに「BigQuery Admin」を割り当てます。
- 「作成」後、「キーファイルのダウンロード」からJSON形式の鍵ファイル（例:
service-account.json）を保存します。
補足：JSONファイルはセキュリティ上、適切な場所に保管し、Gitなどへのコミットは避けてください。失われる場合、再生成が必要になります。
OAuth2認証の手順と資格情報の準備
OAuth2認証を使用することで、BigQuery APIに安全にアクセスできます。この手順では、環境変数に資格情報を設定し、Pythonコード内で読み込む方法を紹介します。
環境変数へのクレデンシャル設定
サービスアカウントのJSONファイルを使ってOAuth2認証を行うには、以下のような環境変数を事前に準備します。
|
1 2 |
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" |
注意：このパスは、
service-account.jsonが保存されている実際の場所に置き換えてください。Linux/Macなら.bashrcや.zshrcに追記し、WindowsではPowerShellで[Environment]::SetEnvironmentVariable()を使用します。
Service Account JSONファイルの読み込み
Pythonコード内ではgoogle.authモジュールを使ってJSONファイルを読み込みます。以下は認証処理の基本的な流れです：
|
1 2 3 4 5 6 |
from google.oauth2 import service_account credentials = service_account.Credentials.from_service_account_file( '/path/to/service-account.json', scopes=['https://www.googleapis.com/auth/bigquery'] ) |
ポイント：
scopesパラメータでアクセス権限を指定します。BigQuery APIの場合、https://www.googleapis.com/auth/bigqueryが必須です。
Pythonクライアントライブラリのインストール方法
PythonからBigQueryに接続するためには、google-cloud-bigqueryライブラリが必要です。以下のようにpipでインストールします。
必要なパッケージとバージョン一覧
| パッケージ名 | 概要 | 推奨バージョン |
|---|---|---|
google-cloud-bigquery |
BigQuery APIへのアクセスを提供 | 3.10.0以上 |
pandas |
DataFrameによるデータ操作に使用 | 最新版 |
|
1 2 |
pip install google-cloud-bigquery pandas |
注意：Pythonバージョンとライブラリの互換性には注意が必要です。3.7以上が推奨されます。
pipによるインストール手順
- 既存環境との互換性を考慮し、
requirements.txtに記載して管理する方法も有効です。 - 特定バージョンの指定が必要な場合は以下のようにします：
|
1 2 |
pip install google-cloud-bigquery==3.10.0 |
補足：最新版が常に最適とは限らないため、テスト環境で動作確認をしたバージョンを使用することを推奨します。
BigQueryへのデータ挿入とクエリ実行サンプルコード
BigQueryは、DataFrameから直接データをアップロードできるほか、SQLクエリを実行して結果を得ることも可能です。以下に代表的な処理のコード例を紹介します。
DataFrameからのデータ挿入処理
Pandas DataFrameを使ってBigQueryへデータを挿入するには、to_gbq()関数を使用します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
from google.cloud import bigquery import pandas as pd # BigQueryクライアントの初期化 client = bigquery.Client() # サンプルDataFrameの作成 df = pd.DataFrame({ 'name': ['Alice', 'Bob'], 'age': [25, 30] }) # DataFrameをBigQueryに挿入 table_id = "my_dataset.my_table" job_config = bigquery.LoadJobConfig(write_disposition="WRITE_TRUNCATE") job = client.load_table_from_dataframe(df, table_id, job_config=job_config) job.result() |
注意：
write_dispositionパラメータで挿入時の動作を指定できます。"WRITE_TRUNCATE"は既存データを上書きします。
SQLクエリの実行例
BigQueryに登録されたテーブルに対してSQLクエリを実行するには、以下のコードを使用します：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
query = """ SELECT name, AVG(age) AS avg_age FROM `my_dataset.my_table` GROUP BY name; """ # クエリの実行と結果取得 query_job = client.query(query) results = query_job.result() for row in results: print(f"{row.name}: {row.avg_age}") |
ポイント：クエリの実行は非同期に動作し、
result()メソッドで完了を待つ必要があります。
エラーハンドリングのベストプラクティス
BigQuery APIとの接続にはネットワークや認証エラーが発生する可能性があるため、適切なエラーハンドリングが必要です。
例外処理の基本構文
Pythonではtry-exceptブロックを使って異常処理を行います。以下は基本的な使用例です：
|
1 2 3 4 5 6 7 8 9 10 |
from google.api_core.exceptions import GoogleAPICallError try: # BigQuery API呼び出し処理 query_job = client.query(query) except GoogleAPICallError as e: print(f"API呼び出しが失敗しました: {e}") except Exception as e: print(f"予期せぬエラーが発生しました: {e}") |
注意：
google.api_core.exceptionsモジュールには具体的なエラーコードが含まれており、特定の例外に対して対処できます。
ログ出力とリトライロジック
実際には、ログを記録して原因を追跡し、リトライ可能なエラー（例: 一時的なネットワーク障害）に対応することが重要です。以下は簡単なリトライ処理の例です：
|
1 2 3 4 5 6 7 |
from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=5)) def safe_query(query): query_job = client.query(query) return query_job.result() |
補足：
tenacityライブラリは、リトライロジックを簡潔に記述できる便利なツールです。
まとめ
- Google Cloudプロジェクトの初期設定では、プロジェクト作成とAPI有効化が不可欠
- OAuth2認証にはサービスアカウントJSONファイルと環境変数の設定が必要
google-cloud-bigqueryライブラリをpipでインストールし、DataFrameからデータ挿入やSQLクエリ実行が可能- 実際のコードではエラーハンドリングとログ出力を必ず記述し、リトライロジックも検討
記事内のコードをコピーしてすぐに試してみましょう。公式ドキュメントと併用することで効率的な導入手順が得られます。