eBay Sandbox環境の完全セットアップ

2026.03.15

eBay Sandbox環境の完全セットアップ：本番を汚さずAPIをテストする構成管理パターン

前回の記事はこちら

はじめに

本記事は、全42回にわたる「eBay API 実践ガイド」の第2回です。

前回（#1）では堅牢な OAuth トークン管理機構を構築しました。しかし、完成したコードをいきなり本番環境（Production）で動かすのは危険です。出品データの破壊や、誤った注文処理（Fulfillment）を引き起こす可能性があります。

この記事で得られること:

  • eBay Sandbox（テスト環境）の特質と、本番環境との違いの理解。
  • python-dotenv を活用し、コードを1行も書き換えずに Production / Sandbox を切り替える設定管理（Configuration）の実装。
  • テスト自動化（CI/CD）を見据えたアーキテクチャ設計。

背景・なぜこれが重要か (Motivation)

「ハードコードされたエンドポイントやキーを、デプロイ前に手作業で書き換える」。これはバグと事故の温床です。

eBay API では、エンドポイントのドメインが本番と Sandbox で異なります（例: api.ebay.com vs api.sandbox.ebay.com）。また、OAuth のクレデンシャル（Client ID / Secret）も環境ごとに完全に独立しています。

実務においては、「ローカル開発や CI 上の自動テストでは Sandbox を向き、本番サーバーにデプロイされた瞬間のみ Production を向く」 という状態を、環境変数によって強制する設計（Twelve-Factor App の原則）が必須となります。

基本的な使い方（ベースライン）：Sandbox特有の準備

実装に入る前に、eBay Developer Portal で Sandbox 環境の準備を行います。ここが初学者の躓きポイントになりやすいので、要点だけ整理します。

  1. Sandbox 用 Keys の発行: Developer Portal の「Application Keys」から、Sandbox 用の Client ID / Secret を発行します（本番用とは別物です）。
  2. テストアカウントの作成: Sandbox の世界で取引を行うための「架空のセラーアカウント」と「架空のバイヤーアカウント」を作成します（User Tokens > Sandbox User Register）。
  3. Sandbox 用 Token の取得: 前回（#1）の手順を、Sandbox 用の Keys とテストアカウントを使って行い、Sandbox 用の refresh_token を取得します。
深いポイント: 完全に独立した世界
Sandbox は本番環境から切り離されたパラレルワールドです。本番環境にあるあなたの出品データは、Sandbox には一切存在しません。

実務で躓く場面・深いポイント (Core)

ここからは Python の実装です。

環境変数を管理するために python-dotenv を使用し、シングルトン的にアプリケーション全体で設定を共有する eBayConfig クラスを実装します。

1. .env ファイルの設計

プロジェクトのルートディレクトリに .env ファイルを作成します。このファイルは機密情報を含むため、絶対に Git にコミットしてはいけません。 以下のように .gitignore に追加して追跡から除外してください。 

# .gitignore .env
.env.*

次に、.env ファイルの中身を記述します。 

# .env EBAY_ENV=sandbox # Sandbox Credentials EBAY_SANDBOX_CLIENT_ID=your_sandbox_client_id
EBAY_SANDBOX_CLIENT_SECRET=your_sandbox_client_secret
EBAY_SANDBOX_REFRESH_TOKEN=your_sandbox_refresh_token # Production Credentials EBAY_PROD_CLIENT_ID=your_prod_client_id
EBAY_PROD_CLIENT_SECRET=your_prod_client_secret
EBAY_PROD_REFRESH_TOKEN=your_prod_refresh_token

2. 環境をシームレスに切り替える Config クラス

if 文で毎回エンドポイントを切り替えるのは非効率です。環境変数 EBAY_ENV の値に基づいて、適切なエンドポイントとキーを動的に返すクラスを構築します。 

# config.py import os from dotenv import load_dotenv # .env ファイルを読み込む load_dotenv() class eBayConfig: def __init__(self): # デフォルトは安全側に倒して 'sandbox' とする self.env = os.getenv("EBAY_ENV", "sandbox").lower() if self.env not in ["sandbox", "production"]: raise ValueError("EBAY_ENV must be 'sandbox' or 'production'") # 環境に応じたプレフィックスを決定 prefix = "EBAY_PROD" if self.env == "production" else "EBAY_SANDBOX" # クレデンシャルの読み込み self.client_id = os.getenv(f"{prefix}_CLIENT_ID")
        self.client_secret = os.getenv(f"{prefix}_CLIENT_SECRET")
        self.refresh_token = os.getenv(f"{prefix}_REFRESH_TOKEN") # 必須キーの欠落チェック（フェイルファスト） if not all([self.client_id, self.client_secret, self.refresh_token]): raise EnvironmentError(f"Missing required environment variables for {self.env} environment.") # エンドポイントの動的解決 self.base_url = "https://api.ebay.com" if self.env == "production" else "https://api.sandbox.ebay.com" # ※ 今後連載で Trading API を使うためのエンドポイントもここで定義しておくと便利です self.trading_api_url = "https://api.ebay.com/ws/api.dll" if self.env == "production" else "https://api.sandbox.ebay.com/ws/api.dll" # 使い方の例 if __name__ == "__main__":
    config = eBayConfig() print(f"Current Environment: {config.env}") print(f"REST API Base URL: {config.base_url}") print(f"Client ID: {config.client_id[:5]}...") # マスキングして表示

エッジケース処理：なぜフェイルファスト（Fail-Fast）なのか？

if not all([...]) の部分が重要です。環境変数の設定ミスは、実行時エラーではなく、アプリケーションの起動時に即座に検知して落とすべきです（フェイルファストの原則）。これにより、「バッチ処理が3時間走った後にキーがないことに気づいて落ちる」という悲劇を防げます。

Sandbox 環境の注意点 (Caveats)

実装が完了し、さあテストを始めようという前に、Sandbox の限界について理解しておく必要があります。Sandbox は非常に便利ですが、完璧なクローンではありません。以下の点に留意してください。

  • 最新 API の遅延: 新しくリリースされた機能（特に Sell REST API の一部）は、Sandbox での挙動が不安定だったり、反映が遅れたりする場合があります。
  • データのモックアップ: 商品カタログ（GTIN/UPC 検索）など、一部のデータは本番環境ほど充実していません。検索 API のテストで「本番ならヒットするはずの商品が出ない」といったことが起こり得ます。
  • 定期的なメンテナンス: Sandbox は本番よりもメンテナンスによるダウンタイムが頻繁に発生します。

パフォーマンス・スケーリング視点 (深度)

この構成管理パターンは、将来的に CI/CD（継続的インテグレーション）を組む際に真価を発揮します。

CI/CD 環境での自動テスト時は、.env ファイルを配置するのではなく、サーバーの環境変数（シークレットマネージャーなど）として直接 EBAY_ENV=sandbox や各種クレデンシャルを注入します。これにより、開発者のローカル環境から CI サーバー、そして本番サーバーに至るまで、同一の Python コードを一切修正することなく安全に動作させることができます。

第1回との統合：セキュアなAPIクライアントの完成

ここまでくれば、第1回で作成した eBayTokenManager と組み合わせることで、「環境（Sandbox/Prod）を自動判別し、常に有効なトークンを返す堅牢な認証基盤」 が完成します。 

# main.py (第1回と第2回の知識を結合した完成形) from config import eBayConfig from ebay_token_manager import eBayTokenManager # 1. 環境変数を自動解決 config = eBayConfig() # 2. 環境設定をTokenManagerに渡す manager = eBayTokenManager(
    client_id=config.client_id, 
    client_secret=config.client_secret, 
    refresh_token=config.refresh_token,
    environment=config.env
) # 3. トークン取得（SandboxかProductionかは .env の一行で決まる！） token = manager.get_token() print(f"[{config.env}] Token Ready! Token starts with: {token[:15]}...")

これで、今後のすべての API リクエストにおいて、認証と環境分けの悩みが完全に解消されました。

まとめ

本記事では、eBay API の Sandbox 環境の準備から、実稼働を見据えた環境変数による設定管理（Configuration）の実装までを解説しました。

  • ベースライン: Sandbox 用のキーとテストアカウントは本番とは完全に分離されている。
  • 深いポイント: python-dotenv を用い、EBAY_ENV の値一つでクレデンシャルとベース URL を動的に切り替える Config クラスの構築。起動時のフェイルファスト設計。

これにて、「本番を汚さない、安全でスケーラブルな API 実行基盤」 の完成です。

次のステップ

認証と環境の準備が整いました。次回（#3）からは、いよいよ実際の API 呼び出しに入ります。

まずは 「Trading API入門：GeteBayDetailsでサイトメタデータを取得してAPIの構造を理解する」 です。REST API 全盛の今、なぜあえてレガシーな Trading API（SOAP/XML）から学ぶべきなのか？その理由と、実務での活用法を解説します！

トップに戻る