データのアップロード

appcfg.py ツールはデータをアプリケーションのデータストアにアップロードできます。わずかな設定で、新しいデータストア エンティティを CSV ファイルから作成できます。大半のスプレッドシート アプリケーションは CSV ファイルをエクスポートできるため、デベロッパー以外のユーザーおよびその他のアプリケーションは、アプリケーションにインポートするデータを簡単に作成できます。

• remote_api の設定
• Sqlite のインストール（推奨）
• ローダー クラスの作成
• データの準備
• データの App Engine へのアップロード
• データの開発用サーバーへのロード
• コマンド ライン引数

remote_api の設定

データ ローダー機能は、App Engine Python ライブラリに付属のリクエスト ハンドラである remote_api を使用して App Engine で実行されるアプリケーションと通信し、リモート アプリケーションがデータストアにリモートでアクセスするための適切な認証情報を許可します。remote_api を使用するには、app.yaml ファイルで URL を remote_api にマッピングする必要があります。

app.yaml を編集して、次の行を handlers: セクションに追加します:

- url: /remote_api
  script: $PYTHON_LIB/google/appengine/ext/remote_api/handler.py
  login: admin

これにより、remote_api リクエスト ハンドラが URL /remote_api にマッピングされます。任意の URL を使用できます。この URL へのアクセスは、アプリケーションの管理者ユーザーに制限されます。

アプリケーションを更新して、新しい app.yaml と remote_api URL をインストールします:

appcfg.py update

Sqlite のインストール（推奨）

appcfg.py upload_data はアップロードが中断され、データ ファイルの途中から再開する必要がある場合に備えて、データ ファイルを使用してデータのアップロード中に進行状況を記録します。この機能には、進行状況ファイルを管理するために Sqlite 3 ライブラリが必要です。Sqlite 3 がシステムにインストールされていない場合は、Sqlite 3 のダウンロードとインストールについて、Sqlite の Web サイトをご覧ください。

注: Python をソース コードからコンパイルしてシステムにインストールした場合は、Sqlite をインストールした後に Python を Sqlite サポートで再コンパイルする必要があります。

Sqlite が Python にインストールされたことをテストするには、次のコマンドを入力します:

python -c 'import sqlite3'

コマンドから何も出力されない場合は、Sqlite 3 がインストールされています。Sqlite 3 がインストールされていない場合は、ImportError: No module named sqlite3 と出力されます。

Sqlite 3 をインストールする場合は、進行状況ファイルの使用を無効にすることができます。このためには、appcfg.py upload_data に引数として --db_filename=skip を指定します。進行状況ファイルを無効にしてアップロードが中断された場合、CSV ファイルを編集して、アップロードを再開したときに重複したエンティティが作成されないようにする必要があります。

ローダー クラスの作成

appcfg.py upload_data に CSV ファイルの各行をデータストア エンティティに変換する方法を指定するには、Python ソース ファイルにローダー クラスを定義します。このファイルは作成されるエンティティに Model クラスをインポートまたは定義し、インポートしようとするそれぞれの種類についてローダー クラスを定義します。

たとえば、Album という Model クラスがファイル models.py（ツールを実行するディレクトリなど、PYTHONPATH に存在する）に定義されており、次のような内容になっているとします。

from google.appengine.ext import db

class Album(db.Model):
  artist = db.StringProperty()
  title = db.StringProperty()
  publication_date = db.DateProperty()
  length_in_minutes = db.IntegerProperty()

列の順序が、タイトル、アルバム、発行日、分数の CSV ファイルをインポートしたいとします。CSV ファイルには、これらの値のそれぞれを示す文字列が記録されます。

このファイルのローダー クラス ファイルは次のようになります。

import datetime
from google.appengine.ext import db
from google.appengine.tools import bulkloader
import models

class AlbumLoader(bulkloader.Loader):
  def __init__(self):
    bulkloader.Loader.__init__(self, 'Album',
                               [('title', str),
                                ('artist', str),
                                ('publication_date',
                                 lambda x: datetime.datetime.strptime(x, '%m/%d/%Y').date()),
                                ('length_in_minutes', int)
                               ])

loaders = [AlbumLoader]

一括ローダー ツールは loaders というローダー クラス ファイルでグローバル変数を探します。この値は、使用するローダー クラスのリストです。この例では、ツールは AlbumLoader クラスをロードして、種類 Album のエンティティをロードします。

ローダー クラスは __init__() メソッドを定義します。このメソッドは __init__() を Loader クラスで呼び出します。最初の引数は self で、ローダー クラスのインスタンスです。2 番目の引数は文字列としてのデータストアの種類の名前で、この場合は 'Album' です。3 番目の引数はデータのシーケンスで、各データにはプロパティの名前（文字列）と変換関数が含まれています。変換関数は文字列を受け取って、データストア値型の 1 つを返す必要があります。

この例では、'title' と 'artist' プロパティは両方とも文字列値を受け取り、変換関数は str で文字列コンストラクタです。'length_in_minutes' プロパティは整数を受け取り、int コンストラクタは文字列を受け取って整数値に変換します。

'publication_date' プロパティでは、モデルでは datetime 値が必要です。この場合、データ ファイルを見れば発行日は mm/dd/yyyy の形式で表現されることがわかります。変換関数は Python ラムダ式（短い関数）で、文字列を受け取り、datetime.datetime.strptime() にパターン付きで渡して値を datetime.datetime 形式に変換し、date() メソッドを呼び出して最終的に datetime.date 値を取得します。

変換関数が例外を発生させたり Model クラスの要件に適合する値を返さなかったりする場合、データ ファイルの処理は停止し、エラーが報告されます。進行状況ファイル（上述の Sqlite）を使用している場合、CSV ファイルを修正して、アップロードを再実行してエラーが発生した行から再開できます。

ローダー クラス定義を含むファイル名が album_loader.py の場合、appcfg.py upload_data に次の引数を指定することができます: --config_file=album_loader.py

データの準備

appcfg.py upload_data は CSV（Comma Separated Value）形式でファイル形式のデータを受け取ります。これはシンプルなテキスト ファイルで、1 行に 1 列、各列がカンマ（,）で区切られている値のテーブルを示しています。値に 1 つ以上のカンマがある場合、値は二重引用符（"）で囲まれます。値に二重引用符がある場合は、二重引用符は二重に使用されます（""）。ツールは Python 標準ライブラリから csv モジュールを使用して、データ ファイルを解析します。

ファイルでは UTF-8 エンコードのテキスト データを使用する必要があります。UTF-8 エンコードは ASCII エンコードと互換性があるため、CSV を ASCII として保存する任意のスプレッドシート アプリケーションでも動作します。

大半のスプレッドシート アプリケーションは、シートを CSV ファイルとしてエクスポートできます。Google スプレッドシートからシートを CSV としてエクスポートするには、[ファイル] メニュー > [エクスポート] > [.csv シートのみ] を選択して、開いたブラウザ ウィンドウからファイルを保存します。

ロードする CSV ファイルの名前が album_data.csv の場合、appcfg.py upload_data を次の引数に指定してください: --filename=album_data.csv

CSV ファイルの最初の行がデータではない場合（ヘッダー行の場合など）、次のオプションを使用して最初の行をスキップします: --has_header

データの App Engine へのアップロード

データのアップロードを開始するには、appcfg.py upload_data に適切な引数を使用して実行します:

appcfg.py upload_data --config_file=album_loader.py --filename=album_data.csv --kind=Album <app-directory>

Google Apps ドメイン名を使用していて、このドメインのアカウントを使用してログインするために appcfg.py が必要な場合、--auth_domain=... オプションを指定して、その値をドメイン名にする必要があります。

データの開発用サーバーへのロード

アップロードする前にアプリケーションでデータがどのように機能するかテストしたい場合は、開発用サーバーにロードできます。--url オプションを使用して、開発用サーバー URL にあるツールを参照します。次に例を示します。

appcfg.py upload_data --config_file=album_loader.py --filename=album_data.csv --kind=Album --url=http://localhost:8080/remote_api <app-directory>

コマンド ライン引数

appcfg.py upload_data コマンドは次の引数を受け取ります:appcfg.py がすべての操作について受け取るその他のオプションについては、Python アプリケーションのアップロードと管理: コマンドライン引数もご覧ください。

appcfg.py upload_data [options] <app-directory>

--filename=...

必須です。ロードする CSV データ ファイルへのパス。

--kind=...

必須です。新しいエンティティを作成するために使用する、データストアの種類の名前。

--config_file=...

必須です。アップロードで作成される可能性があるエンティティの種類の Model クラス、およびそれぞれの種類の Loader クラスをインポートまたは定義する、Python ソース ファイル。appcfg.py upload_data はこのファイルを評価するときに、Loader 基本クラスをローカルの名前空間に提供します。

--loader_opts=...

Loader クラスの initialize() メソッドに渡すオプション。このメソッドを実装して、Loader クラスに引数を渡せます。

--log_file=...

アップロードについてのロギング情報を書き込むファイルの名前。デフォルトでは、bulkloader-log-timestamp という名前のファイルが現在の作業ディレクトリに作成されます（ここで、timestamp はツールが実行された時刻）。

--auth_domain=...

remote_api に接続するために使用される、アカウントの認証ドメインの名前。Google Apps ドメインを使用していて、Google Apps アカウントを使用して appcfg.py にログインする必要がある場合、ドメイン名にこのオプションを指定します。

--num_threads=#

新しいエンティティを同時にアップロードするときに作成されるスレッド数。デフォルトは 10 です。

--batch_size=#

remote_api の呼び出しごとに作成されるエンティティ数。大規模なエンティティの場合は、バッチ サイズを小さくしてバッチごとに転送されるデータ量を制限します。デフォルトは 10 です。

--bandwidth_limit=#

すべてのスレッドの送信に適用される、秒単位のバイトの最大合計数。バーストによってこの最大値を超過することがありますが、全体的に見て帯域幅はこの数値未満になります。デフォルトは 250,000 バイト/秒です。

--rps_limit=#

すべてのスレッドの送信に適用される、秒単位のレコードの最大合計数。デフォルトは 20 です。

--http_limit=#

すべてのスレッドの送信に適用される、秒単位の HTTP リクエストの最大合計数。デフォルトは 1 秒に 7.5（2 秒で 15）です。

--db_filename=...

この実行について進行状況ファイルに使用するファイル名。指定されない場合、このファイルは bulkloader-progress-timestamp という名前になります。timestamp はコマンドが実行された時刻です。この引数に値 skip が指定された場合、アップロードでは進行状況ファイルを使用しません。

--has_header

指定された場合、CSV ファイルの最初の行をヘッダー行と仮定してスキップします。

--app_id=...

アプリケーションの app.yaml ファイルで指定されたアプリケーション ID とは異なる場合の、アプリケーション ID。

--url=...

データストアに接続するために使用する、remote_api ハンドラの URL。デフォルトで、これはアプリケーションの app.yaml ファイルから派生します。