データのアップロードとダウンロード

一括ローダー ツールを使用して、アプリケーションのデータストアへのデータのアップロードと、データストアからのダウンロードを行うことができます。わずかな設定で、新しいデータストア エンティティを CSV ファイルや XML ファイルからアップロードしたり、エンティティ データを CSV ファイル、XML ファイル、テキスト ファイルにダウンロードしたりできます。ほとんどのスプレッドシート アプリケーションで CSV ファイルのエクスポートが可能なので、デベロッパー以外のユーザーでも、他のアプリケーションでも、作成したアプリケーションにインポートするデータを簡単に作成できます。アップロードやダウンロードのロジックをカスタマイズして、さまざまな種類のファイルを使用できます。他のデータ処理を行うこともできます。

一括ローダー ツールを使用すれば、コードや設定を追加することなく、すべてのデータストア エンティティをバックアップや復元に適した形式でダウンロードしたりアップロードしたりできます。アップロード/ダウンロード データの形式を指定する設定ファイルを使用して、一括ローダーを設定します。一括ローダー自体を使用して、アプリケーションのデータストアに基づいて自動的に設定ファイルを生成し、後でその設定ファイルを必要に応じて編集することもできます。

一括ローダーは、appcfg.py コマンドで使用することができます。

• remote_api の設定
• 全データのダウンロードとアップロード
• 一括ローダーの設定
• 自動設定の使用
• 設定ファイルの編集
• 設定ファイルのリファレンス詳細
• （非推奨）コードを使用する設定方法

remote_api の設定

一括ローダー ツールは、remote_api を使用して App Engine で実行されるアプリケーションと通信します。remote_api は、App Engine ランタイム環境に含まれる要求ハンドラで、適切な認証情報を持った遠隔のアプリケーションがデータストアにリモートでアクセスできるようにします。remote_api をインストールするには、builtins ディレクティブを使用した自動インストールと、url ディレクティブを使用した手動インストールの 2 つの方法があります。

ヒント: Java アプリケーションをお持ちの場合は、Java ランタイム環境に含まれる Java 版の remote_api ハンドラをインストールすれば、Python appcfg.py ツールを使用できます。ハンドラのサーブレット クラスは com.google.apphosting.utils.remoteapi.RemoteApiServlet です。

builtins ディレクティブを使用した remote_api のインストール

app.yaml を編集して、次の設定を app.yaml に追加します。

builtins:
- remote_api: on

このディレクティブは、remote_api の include.yaml ファイルを検索し、要求ハンドラを /_ah/remote_api にマッピングします。この URL にアクセスできるのは、アプリケーション管理者だけです。

builtins ディレクティブを追加したら、変更した app.yaml を使用してアプリケーションを更新する必要があります。

appcfg.py update <app-directory>

警告: remote_api のパスは、アプリケーション全体で同じパスを使用する必要があります。現在 url ディレクティブを使用しているアプリケーションを、builtins ディレクティブを使用するように切り替える場合、remote_api の新しいインストール パス（_ah/remote_api）が反映されるようにコードを更新する必要があります。

url ディレクティブを使用した remote_api のインストール

remote_api を独自のパスにインストールする場合は、builtins は使用せず、代わりに次のように url ハンドラでそのパスを指定します。

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

これにより、remote_api 要求ハンドラがアプリケーションの URL /remote_api にマッピングされます。任意の URL を使用できます。この URL にアクセスできるのは、アプリケーション管理者だけです。

注: このエントリは必ず、URL の照合を行うすべてのワイルドカード エントリ（URL マッピングで * を含むエントリ）の上に指定するようにしてください。

url ディレクティブを追加したら、次のようにアプリケーションを更新して新しい app.yaml と remote_api URL をインストールする必要があります。

appcfg.py update <app-directory>

全データのダウンロードとアップロード

ある種類のすべてのエンティティを、バックアップや復元に適した形式でダウンロードしたりアップロードしたりできます。コードや設定を追加する必要はありません。すべての種類に属するすべてのエンティティをダウンロードするには、次のコマンドを実行します。

appcfg.py download_data --application=<app-id> --url=http://<appname>.appspot.com/[remote_api_path] --filename=<data-filename>

また、--kind=... 引数を使用して、特定の種類のすべてのエンティティをダウンロードすることもできます。

appcfg.py download_data --application=<app-id> --kind=<kind> --url=http://<appname>.appspot.com/[remote_api_path] --filename=<data-filename>

注: すべての種類のすべてのエンティティのダウンロードは、App Engine でのみ動作します。開発用サーバーでは動作しません。

appcfg.py download_data で作成したファイルからアプリケーションのデータストアにデータをアップロードするには、次のコマンドを実行します。

appcfg.py upload_data --application=<app-id> --kind=<kind> --filename=<data-filename> <app-directory>

データをダウンロードすると、元のキーと共にエンティティが格納されます。データをアップロードするときは、元のキーを使用します。アップロードするエンティティと同じキーを持つエンティティがデータストアに存在する場合、そのエンティティは上書きされます。

upload_data を使用して、ダンプ元のアプリケーションのデータを上書きしたり、別のアプリケーションにデータをアップロードしたりできます。数値のシステム ID を持つエンティティは、同じ ID でアップロードされ、参照プロパティも保持されます。

一括ローダーの設定

一括ローダーは設定ファイルを使用して、アップロード/ダウンロードするデータを記述します。一括ローダー自体を使用して、これらの設定ファイルを自動生成することができます。既存のアプリケーションの設定ファイルを生成するには、create_bulkloader_config 処理を使用して一括ローダーを呼び出します。設定ファイルが生成されたら、ファイルの詳細情報を編集してから使用します。

自動設定の使用

一括ローダーは bulkloader.yaml ファイルを使用して、アップロード時やダウンロード時にデータを変換する方法を記述します。このファイルには、ヘッダーと、その後に変換リストが含まれます。個々の変換は 2 段階に分かれます。外部データから中間形式への変換と、中間形式からデータストア エンティティへの変換です。

データをインポートする場合、最初の変換では、外部ソース（CSV ファイルや XML ファイルなど）からデータを読み取り、ファイルの内容を表す中間形式（Python ディクショナリ）に変換されます。2 番目の変換では、データが中間形式から App Engine データストア エンティティに変換されます。データをエクスポートする場合は、この逆の処理が行われます。エンティティはまず中間形式に変換されてから、外部形式に変換されます。

一括ローダーを実行して bulkloader.yaml ファイルを自動生成する場合、一括ローダーはデータストアの統計情報を調べ、アプリケーションのデータの種類やプロパティに基づいて変換を作成します。データストアの統計情報には 24 時間以内の情報が含まれます。そのため、スキーマを変更しても、生成された設定ファイルにその変更内容がすぐに反映されていない場合があります。

データストアの統計情報に基づいて自動的に bulkloader.yaml ファイルを生成するには、次のように create_bulkloader_config 処理で一括ローダーを実行します。

appcfg.py create_bulkloader_config --filename=bulkloader.yaml 

ヒント: Java アプリケーションをお持ちの場合は、アプリケーション ディレクトリではなく、次のようにアプリケーションの remote_api ハンドラの URL を指定します。
appcfg.py create_bulkloader_config --filename=bulkloader.yaml --url=http://<appname>.appspot.com/remote_api

注: 一括ローダーを使用した設定ファイルの生成は、App Engine でのみ動作します。開発用サーバーでは動作しません。

生成されたファイルは、一括ローダー ツールを再実行してインポート/エクスポートを実行するときに読み込まれます。create_bulkloader_config 処理で一括ローダーを実行した場合の出力例を次に示します。

[INFO    ] Logging to bulkloader-log-20100516.144319
[INFO    ] Throttling transfers:
[INFO    ] Bandwidth: 250000 bytes/second
[INFO    ] HTTP connections: 8/second
[INFO    ] Entities inserted/fetched/modified: 20/second
[INFO    ] Batch Size: 100
[INFO    ] Opening database: bulkloader-progress-20100516.144319.sql3
[INFO    ] Opening database: bulkloader-results-20100516.144319.sql3
[INFO    ] Connecting to test-app.appspot.com/remote_api
No handlers could be found for logger "google.appengine.tools.appengine_rpc"
[INFO    ] Downloading kinds: ['__Stat_PropertyType_PropertyName_Kind__']
.
[INFO    ] Have 64 entities, 0 previously transferred
[INFO    ] 64 entities (23986 bytes) transferred in 1.9 seconds

生成された bulkloader.yaml ファイルの各セクションについて説明します。最初のセクションは次のとおりです。

# Autogenerated bulkloader.yaml file.
# You must edit this file before using it. TODO: Remove this line when done.
# At a minimum address the items marked with TODO:
#  * Fill in connector and connector_options
#  * Review the property map
#    - Ensure the 'external_name' matches the name of your CSV column,
#      XML tag, etc.
#    - Check that __key__ property is what you want. Its value will become
#      the key name on import, and on export the value will be the Key
#      object. If you would like automatic key generation on import and
#      omitting the key on export, you can remove the entire __key__
#      property from the property map.

生成されたファイルは、実際のデータで使用する前に編集する必要があります。ファイルのはじめの部分では、ファイル内でどの部分を編集すべきかについて説明しています。

次のセクションでは、インポートする Python モジュールの一覧を示しています。

# If you have module(s) with your model classes, add them here. Also
# change the kind properties to model_class.
python_preamble:
- import: google.appengine.ext.bulkload.transform
- import: google.appengine.ext.db
- import: re
- import: base64

一括ローダーでインポート/エクスポートする際に追加の Python モジュールをインポートする場合以外は、このセクションを編集する必要はないでしょう。

bulkloader.yaml ファイルの次のセクションでは、入力時や出力時のデータの変換方法について説明しています。

transformers:
- kind: Permission
  connector: # TODO: Choose a connector here: csv, simplexml, etc...
  connector_options:
    # TODO: Add connector options here--these are specific to each connector.
  property_map:
    - property: __key__
      external_name: key
      export_transform: transform.key_id_or_name_as_string
 
    - property: account
      external_name: account
      # Type: Key Stats: 119 properties of this type in this kind.
      import_transform: transform.create_foreign_key('TODO: fill in Kind name')
      export_transform: transform.key_id_or_name_as_string
 
    - property: invite_nonce
      external_name: invite_nonce
      # Type: String Stats: 19 properties of this type in this kind.
 
    - property: role
      external_name: role
      # Type: Integer Stats: 119 properties of this type in this kind.
      import_transform: transform.none_if_empty(int)
 
    - property: user
      external_name: user
      # Type: Key Stats: 119 properties of this type in this kind.
      import_transform: transform.create_foreign_key('TODO: fill in Kind name')
      export_transform: transform.key_id_or_name_as_string

bulkloader.yaml ファイルには、処理する種類ごとの一連の変換が含まれます。生成されたファイルには、データストア内の各種類ごとに一連の変換が含まれます。上記の例では、種類は permission の 1 種類で、connector（ファイルの編集時に書き込んだもので、データの外部形式を指定）、オプションの connector_options（connector の各種設定やフラグを指定）、property_map（データのすべてのプロパティを記述）が含まれています。

設定ファイルの編集

bulkloader.yaml ファイルを編集する最初の手順は、コネクタとコネクタ オプションを指定することです。一括ローダーは、データのインポート/エクスポート用に CSV（csv）と XML（xml）のコネクタをサポートしています。テキスト（simpletext）は、エクスポートでのみサポートしています。次の例では、インポート時のデータの読み取りとエクスポート時の書き込みに CSV コネクタを設定します。CSV コネクタのデフォルトのオプションを使用します。デフォルトでは、CSV ファイルの 1 行目から列名を読み取り、エクスポート時には列名を 1 行目に書き込みます。

- kind: Permission
  connector: csv

次のセクションでは、データのプロパティを記述しています。各プロパティ エントリには、インポート/エクスポート時にデータを変換する方法が指定されています。自動生成されたファイルには、一括ローダーで特定した 4 つのプロパティと __key__ という擬似プロパティが含まれています。各プロパティには外部名が含まれ、オプションでインポート/エクスポートの変換が含まれます。これらは、データストアと外部形式の間でデータを変換する方法を指定しています。また、元のファイルの TODO 文字列を変更して、2 つの参照プロパティの種類名を追加する必要があります。編集後のプロパティのセクションは次のとおりです。

property_map:
    - property: __key__
      external_name: key
      export_transform: transform.key_id_or_name_as_string
 
    - property: account
      external_name: account
      import_transform: transform.create_foreign_key('Account')
      export_transform: transform.key_id_or_name_as_string
 
    - property: invite_nonce
      external_name: invite_nonce
 
    - property: role
      external_name: role
      import_transform: transform.none_if_empty(int)
 
    - property: user
      external_name: user
      import_transform: transform.create_foreign_key('User')
      export_transform: transform.key_id_or_name_as_string

bulkloader.yaml ファイルの編集が完了したら、外部 CSV ファイルからデータストアにデータのインポートができるようになります。

appcfg.py upload_data --config_file=bulkloader.yaml --filename=users.csv --kind=Permission 

ヒント: Java アプリケーションの場合:
appcfg.py upload_data --config_file=bulkloader.yaml --filename=users.csv --kind=Permission --url=http://test-app.appspot.com/remote_api

次の例に示すコマンド ラインのように、同じ bulkloader.yaml ファイルを使用してデータをエクスポートすることができます。

appcfg.py download_data --config_file=bulkloader.yaml --filename=users.csv --kind=Permission --url=<app-directory>

ヒント: Java アプリケーションの場合:
appcfg.py download_data --config_file=bulkloader.yaml --filename=users.csv --kind=Permission --url=http://test-app.appspot.com/remote_api

この appcfg.py 呼び出しでは、アプリケーションのデータストアのデータが exported_data.csv という CSV ファイルにエクスポートされます。

設定ファイルのリファレンス詳細

ここでは、bulkloader.yaml ファイルの形式と appcfg.py ツールのオプションについて説明します。

ファイルの先頭にあるヘッダーには、ファイル全体に適用される情報が含まれます。このセクションを使用して、インポートする Python モジュールを指定します。

変換セクションには、エンティティの種類と変換情報が示されます。各エンティティは、はじめに種類を指定します。種類の代わりにモデル クラスを指定することもできます。ファイルで、各エンティティの種類について、コネクタ（csv、xml、simpletext（エクスポートのみ））と、オプションでコネクタ オプション、プロパティ マップを指定します。プロパティ マップでは、各プロパティについて、外部名と、必要に応じてインポート、エクスポートの変換を指定します。

コネクタのオプションは次のとおりです。

csv コネクタ

encoding

utf-8（デフォルト）や windows-1252 など、任意の Python 標準エンコード形式です。

column_list

ここで列に指定した一連の名前を、インポート/エクスポート時に使用します。指定しない場合、1 行目のデータを使用して各列の external_name を計算し、2 行目からデータの読み込みや書き込みを行います。

skip_import_header_row

true の場合、インポート時にヘッダー行が無視されます。

print_export_header_row

true の場合、エクスポート時にヘッダー行が出力されます。

import_arguments

インポート時の、Python CSV モジュール用の追加のキーワード引数です。TSV ファイルには dialect: excel-tab を使用します。

export_arguments

エクスポート時の、Python CSV モジュール用の追加のキーワード引数です。

simplexml コネクタ

xpath_to_nodes

読み取るノードを指定する xpath です。/node1/node2 という形式の基本的なクエリはサポートされていますが、それ以外はサポートされていない場合があります。別の形式を指定すると、エクスポートできなくなる可能性があります。ネームスペースは、完全にはサポートされていません。

style

指定できる値は、element_centric と attribute_centric です。xpath_to_nodes によって検索されたノードの子ノードが中間形式に変換されます。style 引数は、検索したノードの属性を使用するか（attribute_centric）、子ノードを使用するか（element_centric）を決定します。また、ノード全体も __node__ として渡されます。

simpletext コネクタ

template

エクスポートする各レコードに対して使用する、Python dict の補間文字列です。

prolog（オプション）

各レコード出力の前に書き込まれます。

epilog（オプション）

各レコード出力の後に書き込まれます。

mode（オプション）

text（デフォルト）

テキスト ファイルのモードです。レコード間に改行が挿入されます。

nonewline

テキスト ファイルのモードです。改行は挿入されません。

binary

バイナリ ファイルのモードです。改行は挿入されません。

プロパティ マップ セクションは、エンティティと中間形式の間の変換の詳細を定義します。プロパティ マップの要素は次のとおりです。

property

エンティティまたはモデルで定義されるプロパティ名です。

external_name

1 つのプロパティ（CSV の 1 列など）を、中間ディクショナリの 1 エントリにマッピングします。

import_template

Python の文字列補間を使用して、1 つのプロパティに複数のディクショナリ アイテムを指定します。

import_transform

引数を 1 つ使用する関数の場合、external_name 文字列または import_template 文字列に基づいて正しい値と型のデータを返します。例としては、組み込みの Python 変換演算子（float など）や、transform で提供されるヘルパー関数のいずれか（get_date_time や generate_foreign_key など）、独自のライブラリで提供している関数、インラインのラムダ関数などがあります。キーワード引数 bulkload_state と 2 つの引数を使用する関数の場合、エンティティに関する次の有用な情報を返します。bulkload_state.current_entity は現在処理中のエンティティ、bulkload_state.current_dictionary は現在エクスポート中のディクショナリ、bulkload_state.filename は appcfg.py に渡された --filename 引数です。

export_transform

import_transform と同様です。ただし、エクスポート時に実行されます。

export

import_template と同様です。ただし、エクスポート時に実行され、一連の external_name/export_transform 値として指定されます。

インポート時に作成される各エンティティにはキーがありす。キーを指定しないと、データストアによってキーが自動生成されます。インポート データからキーを使用するか計算する場合は、プロパティ マップと同じ構文（external_name、import_template など）を使用してキーを指定します。

データに対してプロパティ マップでは簡単に記述できないような追加処理を行いたい場合は、エンティティを任意の方法で変更するか、インポート時に複数のエンティティを返すような関数を指定することができます。この機能を使用するには、次のいずれかまたは両方を変換エントリに追加します。

post_import_function(input_dict, instance, bulkload_state_copy) functionName

この関数は、None（このレコードのインポートをスキップします）か、1 つのエンティティ（通常は渡された instance 引数）、インポートする複数のエンティティのリストのいずれかを返す必要があります。

post_export_function(instance, export_dict, bulkload_state) functionName

この関数は、None（この結果をスキップします）か、エンティティを含む dict（通常は渡された export_dict 引数）のいずれかを返す必要があります。

注: パフォーマンス上の理由から、エクスポート時にはモデル クラスへの変換はスキップされます。モデル クラスに実行したいコードがある場合は、use_model_on_export を使用します。

(非推奨）コードを使用する設定方法

注: ここから先は、バージョン 1.3.4 以前に動作していた一括ローダーの説明です。以前のバージョンでは、設定ファイルではなく、Python コードを使用してデータのアップロード/ダウンロードを設定していました。この情報は以前のバージョンを使用しているユーザーの参照用として残してありますが、今後これらの機能はサポートされくなる場合があります。

このセクションでは、一括ローダーを設定ファイルではなく、コードを使用して設定する方法について説明します。

Loader クラスの作成

データをアップロードする場合は、appcfg.py にデータ ファイル内の各行をデータストア エンティティに変換する方法を知らせる必要があります。これを行うには、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 というローダー クラス ファイル内でグローバル変数を検索します。その値は使用するローダー クラスの一覧です。この例では、種類 Album のエンティティをロードするために、ツールで AlbumLoader クラスをロードしています。

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

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

'publication_date' プロパティの場合、モデルには datetime 値が必要です。この例では、データ ファイルを見ると、発売日が mm/dd/yyyy の形式で表されていることがわかります。変換関数は文字列を受け取る Python のラムダ式（短い関数）で、値を datetime.datetime に解析するパターンと共に文字列を datetime.datetime.strptime() に渡します。次に 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 つ以上のカンマが含まれる場合は、値を二重引用符（"）で囲みます。値に二重引用符が含まれる場合、二重引用符を 2 つ（""）使用します。ツールは Python 標準ライブラリの csv モジュールを使用して、データ ファイルを解析します。

ファイルでは UTF-8 エンコードのテキスト データを使用する必要があります。UTF-8 エンコードは ASCII エンコードと互換性があるため、CSV を ASCII として保存するスプレッドシート アプリケーションすべてを使用できます。CSV ファイルに UTF-8 文字が含まれる場合、Loader クラスで文字をデコードする必要があります。UTF-8 のタイトルとアーティストをサポートする AlbumLoader の例を次に示します。

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', lambda x: x.decode('utf-8')),
                                    ('artist', lambda x: x.decode('utf-8')),
                                    ('publication_date',
                                     lambda x: datetime.datetime.strptime(x, '%m/%d/%Y').date()),
                                    ('length_in_minutes', int)
                                   ])

loaders = [AlbumLoader]

ほとんどのスプレッドシート アプリケーションで、シートを 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=... オプション（値はドメイン名です）を指定する必要があります。

転送が中断されても、--db_filename=... 引数を使用して、中断された場所から転送を再開することができます。値はツールで作成された進捗状況ファイルの名前です。この名前は転送を開始したときに --db_filename 引数で指定した名前か、タイムスタンプを含むデフォルト名です。この場合、sqlite3 をインストール済みで、--db_filename=skip を使用して進捗状況ファイルを無効にしていないものとします。

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

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

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

Exporter クラスの作成

データをダウンロードするには、appcfg.py にデータストア エンティティをファイルにエクスポートする方法を指示する必要があります。これには、アップロード時のローダー クラスと同様、Python コードのファイルを使用します。このファイルで Model クラスをインポートするか定義し、エクスポートしたい種類ごとにエクスポータ クラスを定義し、使用できるエクスポータ クラスをグローバル変数で宣言します。

上記で定義した Album Model クラスの例を引き続き使用して説明すると、次のファイルは、ローダー クラスで使用する形式と同じ形式で CSV ファイルを生成するエクスポータを定義しています。

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

class AlbumExporter(bulkloader.Exporter):
    def __init__(self):
        bulkloader.Exporter.__init__(self, 'Album',
                                     [('title', str, None),
                                      ('artist', str, None),
                                      ('publication_date', str, None),
                                      ('length_in_minutes', str, None)
                                     ])

exporters = [AlbumExporter]

エクスポータ クラスはローダー クラスと似ています。エクスポータ クラスは、__init__() を Exporter クラスで呼び出す __init__() メソッドを定義します。1 つ目の引数は self で、エクスポータのインスタンスです。2 つ目の引数はエクスポートするデータストアの種類名で、文字列で指定します。3 つ目の引数は一連のタプルで、エクスポートする各エンティティ プロパティに 1 つのタプルが対応しています。

各タプルには、次の 3 つの要素があります。プロパティ名、プロパティ値を受け取って str に変換する関数、エンティティにプロパティが設定されていない場合のデフォルト値です。デフォルト値が None の場合、そのプロパティを持たないエンティティをエクスポートしようとすると、エクスポータは例外を送出します。

エクスポータによって作成された CSV ファイルでは、1 つのエンティティが 1 行で示され、指定されたプロパティが 1 列に順に並んでいます。列の順番は、プロパティが表示されている順番と同じです。

ヒント: ローダー クラスとエクスポータ クラスを同じファイル内に定義して、appcfg.py upload_data と appcfg.py download_data に同じ引数を使用すると、データを双方向で転送することができます。

App Engine からのデータのダウンロード

データのダウンロードを開始するには、次のように適切な引数を指定して appcfg.py download_data を実行します。

appcfg.py download_data --config_file=album_loader.py --filename=album_data_archive.csv --kind=Album <app-directory>

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

転送が中断されても、--db_filename=... 引数と --result_db_filename=... 引数を使用して、中断された場所から転送を再開することができます。これらの引数は、ツールで作成された進捗状況ファイルと結果ファイルの名前です。これらの名前は転送を開始したときに引数で指定した名前か、タイムスタンプを含むデフォルト名です。この場合、sqlite3 をインストール済みで、--db_filename=skip を使用して進捗状況ファイルを無効にしていないものとします。

コマンド ライン引数

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 ドメインを使用していて、appcfg.py を使用して Google Apps アカウントにログインする必要がある場合、このオプションを使用してドメイン名を指定します。

--num_threads=#

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

--batch_size=#

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

--bandwidth_limit=#

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

--rps_limit=#

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

--http_limit=#

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

--db_filename=...

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

--has_header

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

--application=...

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

--url=...

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

--dry_run

データストアを実際には呼び出さず、それ以外のすべてが動作することの確認だけを行います。

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

download_data の引数は upload_data の引数と同じです。--filename 引数には、読み取り元のファイルではなく、書き込み先のファイルを指定します。新しいダウンロードが開始されると、このファイルは上書きされ、中断されたダウンロードが続行されると追加されます。

download_data では次の引数もサポートされています。

--result_db_filename=...

この実行の結果ファイルとして使用するファイル名です。結果ファイルには、エクスポートが終了するまでエクスポートしたデータが格納されます。そのため最終的な出力ファイルをキー順に並べ替えることができます。指定しない場合、このファイルは bulkloader-results-timestamp という名前になります（timestamp はコマンドが実行された時刻です）。この引数に値 skip を指定した場合、アップロードで結果ファイルは使用されません。