Amazon S3 転送
BigQuery Data Transfer Service for Amazon S3 を使用すると、Amazon S3 から BigQuery への定期的な読み込みジョブを自動的にスケジュールし、管理できます。
始める前に
Amazon S3 転送を作成する前に:
- BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
- データを保存する BigQuery データセットを作成します。
- 転送用に宛先テーブルを作成し、スキーマ定義を指定します。宛先テーブルは、テーブルの命名規則に従う必要があります。宛先テーブル名でもパラメータがサポートされています。
- Amazon S3 の URI、アクセスキー ID、シークレット アクセスキーを取得します。アクセスキーの管理については、AWS のドキュメントをご覧ください。
- Pub/Sub の転送実行通知を設定する場合は、
pubsub.topics.setIamPolicy
権限が必要です。メール通知を設定するだけの場合、Pub/Sub の権限は必要ありません。詳細については、BigQuery Data Transfer Service の実行通知をご覧ください。
制限事項
Amazon S3 転送には、次の制限があります。
- 現時点では、Amazon S3 URI のバケット部分はパラメータ化できません。
- Write disposition パラメータを
WRITE_TRUNCATE
に設定した Amazon S3 からの転送では、実行時にすべての一致するファイルが Google Cloud に転送されます。これにより、追加の Amazon S3 の下り費用が発生する場合があります。実行中に転送されるファイルの詳細については、プレフィックス マッチングまたはワイルドカード マッチングの影響をご覧ください。 - AWS GovCloud(
us-gov
)リージョンからの転送はサポートされていません。 Amazon S3 のソースデータの形式によっては、追加の制限が適用される場合があります。詳細については、次のトピックをご覧ください。
定期的な転送の最小間隔は 24 時間です。デフォルトの定期的な転送間隔は 24 時間です。
必要な権限
Amazon S3 転送を作成する前に:
転送を作成するユーザーに、BigQuery で必要な次の権限が付与されていることを確認します。
bigquery.transfers.update
(転送を作成する権限)bigquery.datasets.get
とbigquery.datasets.update
の両方(抽出先データセットに対する権限)
bigquery.transfers.update
権限、bigquery.datasets.update
権限、bigquery.datasets.get
権限は IAM 事前定義ロールbigquery.admin
に含まれています。BigQuery Data Transfer Service での IAM ロールの詳細については、アクセス制御をご覧ください。転送を有効にするために必要な権限が構成されたことを確認するには、Amazon S3 のドキュメントをご覧ください。少なくとも、Amazon S3 ソースデータには AWS 管理ポリシー
AmazonS3ReadOnlyAccess
が適用されている必要があります。
Amazon S3 データ転送を設定する
Amazon S3 データ転送を作成するには:
Console
Google Cloud Console の [BigQuery] ページに移動します。
[転送] をクリックします。
[転送を作成] をクリックします。
[転送の作成] ページで、次の操作を行います。
[ソースタイプ] セクションの [ソース] で、[Amazon S3] を選択します。
[転送構成名] セクションの [表示名] に、転送名(例:
My Transfer
)を入力します。転送名には、後で修正が必要になった場合に簡単に識別できる任意の名前を使用できます。[スケジュール オプション] セクションで、[スケジュール] をデフォルト値([すぐに開始可能])のままにするか、[設定した時間に開始] をクリックします。
[繰り返しの頻度] で、転送を実行する頻度のオプションを選択します。次のオプションがあります。
- 毎日(デフォルト)
- 毎週
- 毎月
- カスタム
- オンデマンド
[毎日] 以外のオプションを選択した場合は、追加のオプションが利用可能です。たとえば、[毎週] を選択した場合、曜日を選択するためのオプションが表示されます。
[開始日と実行時間] に、転送を開始する日付と時刻を入力します。[すぐに開始可能] を選択した場合、このオプションは無効になります。
[転送先の設定] セクションの [宛先データセット] で、データを保存するために作成したデータセットを選択します。
[データソースの詳細] セクションで、次の操作を行います。
- [Destination table] に、BigQuery でデータを保存するために作成したテーブルの名前を入力します。宛先テーブルの名前では、パラメータがサポートされています。
- [Amazon S3 URI] に、
s3://mybucket/myfolder/...
の形式で URI を入力します。URI でもパラメータがサポートされています。 - [Access key ID] に、アクセスキー ID を入力します。
- [Secret access key] に、シークレット アクセスキーを入力します。
- [ファイル形式] で、データ形式を選択します。JSON(改行区切り)、CSV、Avro、Parquet、ORC のいずれかを選択できます。
[書き込み処理] で、次のいずれかを選択します。
- [WRITE_APPEND] で、既存の宛先テーブルに新しいデータを追加します。BigQuery の読み込みジョブは
WRITE_APPEND
設定によってトリガーされます。実行ごとに、前回の実行以降に変更されたファイルのみが転送されます。[Write preference] のデフォルト値はWRITE_APPEND
です。 - WRITE_TRUNCATE は、既存の宛先テーブルのデータを上書きします。BigQuery の読み込みジョブは
WRITE_TRUNCATE
設定によってトリガーされます。実行ごとに、前回の転送で転送されたファイルを含むすべての一致ファイルが転送されます。 - 詳細については、
JobConfigurationLoad
のwriteDisposition
フィールドをご覧ください。
- [WRITE_APPEND] で、既存の宛先テーブルに新しいデータを追加します。BigQuery の読み込みジョブは
[Transfer Options - All Formats] セクションでは、以下のように設定します。
- [Number of errors allowed] に、無視できる不良レコードの最大数にあたる整数値を入力します。
- (省略可)[Decimal target type] に、ソースの 10 進数値を変換できる、有効な SQL データ型のカンマ区切りのリストを入力します。変換にどの SQL データ型を選択するかは、次の条件によって決まります。
- 変換に選択したデータ型は、ソースデータの精度とスケールをサポートする次のリスト内の最初のデータ型になります。順序は NUMERIC、BIGNUMERIC、STRING の順になります。
- リストされたデータ型が精度とスケールをサポートしていない場合は、指定されたリストの最も広い範囲をサポートするデータ型が選択されます。ソースデータの読み取り時に、値がサポートされている範囲を超えると、エラーがスローされます。
- データ型 STRING では、すべての精度とスケールの値がサポートされています。
- このフィールドが空の場合、ORC ではデータ型はデフォルトで「NUMERIC、STRING」、その他のファイル形式では「NUMERIC」になります。
- このフィールドに重複するデータ型を含めることはできません。
- このフィールドでリストするデータ型の順序は無視されます。
ファイル形式として CSV または JSON を選択した場合、スキーマに適合しない値を含んだ行を許容するには、[JSON, CSV] セクションで [Ignore unknown values] をオンにします。こうすると、不明な値は無視されるようになります。CSV ファイルでは、行の末尾の余分な値も無視されます。
ファイル形式として CSV を選択した場合は、[CSV] セクションでデータを読み込むための追加の CSV オプションを入力します。
(省略可)[通知オプション] セクションで、次の操作を行います。
[保存] をクリックします。
bq
bq mk
コマンドを入力して、転送作成フラグ --transfer_config
を指定します。
bq mk \ --transfer_config \ --project_id=project_id \ --data_source=data_source \ --display_name=name \ --target_dataset=dataset \ --params='parameters'
ここで
- project_id: 省略可。Google Cloud プロジェクト ID を指定します。
--project_id
で特定のプロジェクトを指定しない場合は、デフォルトのプロジェクトが使用されます。 - data_source: 必須。データソース
amazon_s3
を指定します。 - display_name: 必須。転送構成の表示名を指定します。転送名には、後で修正が必要になった場合に簡単に識別できる任意の名前を使用できます。
- dataset: 必須。転送構成のターゲット データセット。
parameters: 必須。作成される転送構成のパラメータを JSON 形式で指定します。(例:
--params='{"param":"param_value"}'
)。Amazon S3 転送のパラメータは次のとおりです。- destination_table_name_template: 必須。宛先テーブルの名前を指定します。
data_path: 必須。次の形式で Amazon S3 URI を指定します。
s3://mybucket/myfolder/...
URI でもパラメータがサポートされています。
access_key_id: 必須。アクセスキー ID を指定します。
secret_access_key: 必須。シークレット アクセスキーを指定します。
file_format: 省略可。転送するファイルの種類(
CSV
、JSON
、AVRO
、PARQUET
、ORC
)を指定します。デフォルト値はCSV
です。write_disposition: 省略可。
WRITE_APPEND
は、前回の実行以降に変更されたファイルのみを転送します。WRITE_TRUNCATE
は、過去の転送で転送されたファイルを含むすべての一致ファイルを転送します。デフォルトはWRITE_APPEND
です。max_bad_records: 省略可。許可する不良レコードの数を指定します。デフォルトは
0
です。decimal_target_types: 省略可。ソースの 10 進数値を変換できる、有効な SQL データ型のカンマ区切りのリスト。このフィールドが指定されていない場合、ORC ではデータ型はデフォルトで「NUMERIC、STRING」、その他のファイル形式では「NUMERIC」になります。
ignore_unknown_values: 省略可。file_format が
JSON
またはCSV
でない場合は無視されます。データ内の不明な値を無視するかどうかを指定します。field_delimiter: 省略可。
file_format
がCSV
の場合にのみ適用されます。フィールドを区切る文字を指定します。デフォルト値はカンマ(,)です。skip_leading_rows: 省略可。file_format が
CSV
の場合にのみ適用されます。インポートの対象外にするヘッダー行の数を指定します。デフォルト値は0
です。allow_quoted_newlines: 省略可。file_format が
CSV
の場合にのみ適用されます。引用符で囲まれたフィールド内で改行を許可するかどうかを指定します。allow_jagged_rows: 省略可。file_format が
CSV
の場合にのみ適用されます。末尾のオプションの列が欠落している行を許可するかどうかを指定します。欠落した値には NULL が入力されます。
たとえば、次のコマンドは、data_path
の値に s3://mybucket/myfile/*.csv
を使用し、ターゲット データセットとして mydataset
、CSV
として file_format
を指定した、My Transfer
という名前の Amazon S3 転送を作成します。この例では、file_format の CSV
値に関連するオプションのパラメータとして、デフォルト以外の値を使用しています。
この転送はデフォルトのプロジェクトで作成されます。
bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--data_source=amazon_s3
コマンドを実行すると、次のようなメッセージが表示されます。
[URL omitted] Please copy and paste the above URL into your web browser and
follow the instructions to retrieve an authentication code.
指示に従って、認証コードをコマンドラインに貼り付けます。
API
projects.locations.transferConfigs.create
メソッドを使用して、TransferConfig
リソースのインスタンスを指定します。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Java の手順に沿って設定を行ってください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
プレフィックス マッチングまたはワイルドカード マッチングの影響
Amazon S3 API では、プレフィックス マッチングはサポートされていますが、ワイルドカード マッチングはサポートされていません。プレフィックスに一致するすべての Amazon S3 ファイルは Google Cloud に転送されます。ただし、実際に BigQuery に読み込まれるのは、転送構成の Amazon S3 URI に一致するファイルのみです。このため、転送はされても BigQuery に読み込まれないファイルのために、Amazon S3 の下り料金が余分に発生する可能性があります。
たとえば、次のデータパスを考えてみます。
s3://bucket/folder/*/subfolder/*.csv
ソースのロケーションには次のファイルがあります。
s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv
この場合、プレフィックスが s3://bucket/folder/
のすべてのファイルが Google Cloud に転送されます。この例では、file1.csv
と file2.csv
の両方が転送されます。
ただし、実際に BigQuery に読み込まれるのは、s3://bucket/folder/*/subfolder/*.csv
に一致するファイルのみです。この例では、file1.csv
だけが BigQuery に読み込まれます。
トラブルシューティング
よくあるエラーと推奨される解決策について以下に説明します。
Amazon S3 PERMISSION_DENIED エラー
エラー | 推奨される対応 |
---|---|
指定された AWS アクセスキー ID が Google のレコードに存在しません。 | アクセスキーが存在し、ID が正しいことを確認します。 |
計算したリクエストの署名と指定された署名が一致しません。キーと署名方法を確認します。 | 転送構成で対応するシークレット アクセスキーが正しく設定されていることを確認します。 |
ソース S3 バケットのロケーションを取得できませんでした。詳細: アクセスが拒否されました ソース S3 バケットのロケーションを取得できませんでした。詳細: HTTP/1.1 403 Forbidden S3 エラー メッセージ: アクセスが拒否されました |
AWS IAM ユーザーに次の操作を行う権限があることを確認します。
|
サーバーがオブジェクトのアップロードを初期化できません。InvalidObjectState: オブジェクトのストレージ クラスには無効なオペレーションです ソース S3 バケットの場所を取得できませんでした。詳細: このオブジェクトへのアクセスはすべて無効です |
Amazon Glacier にアーカイブされているすべてのオブジェクトを復元します。Amazon Glacier にアーカイブされている Amazon S3 のオブジェクトには、復元するまでアクセスできません。 |
このオブジェクトへのアクセスはすべて無効です。 | 転送構成で Amazon S3 URI が正しく設定されていることを確認します。 |
Amazon S3 転送量の上限エラー
エラー | 推奨される対応 |
---|---|
転送中のファイルの数が上限の 10,000 を超えています。 | Amazon S3 URI に含まれるワイルドカードの数を 1 つだけに減らすことが可能かどうかを評価します。可能であれば、新しい転送構成で再試行します。転送実行ごとの最大ファイル数が増加します。 転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。 |
転送中のファイルのサイズが 16,492,674,416,640 バイトの上限を超えています。 | 転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。 |
一般的な問題
エラー | 推奨される対応 |
---|---|
Amazon S3 から転送されたファイルが BigQuery に読み込まれません。転送ログは次のようになります。 Moving data from Amazon S3 to Google Cloud complete: Moved <NNN> object(s). No new files found matching <Amazon S3 URI>. |
転送構成で Amazon S3 URI が正しく設定されていることを確認します。 転送構成で共通の接頭辞を持つすべてのファイルを読み込むはずであった場合は、Amazon S3 URI の末尾にワイルドカードを使用します。 たとえば、 s3://my-bucket/my-folder/ 内のすべてのファイルを読み込むには、転送構成での Amazon S3 URI は s3://my-bucket/my-folder/* とするだけでなく、s3://my-bucket/my-folder/ として設定する必要があります。 |
その他の問題 | 転送構成のトラブルシューティングをご覧ください。 |
次のステップ
- Amazon S3 転送の概要については、Amazon S3 転送の概要をご覧ください。
- BigQuery Data Transfer Service の概要については、BigQuery Data Transfer Service の概要をご覧ください。
- 転送構成に関する情報の取得、転送構成の一覧表示、転送の実行履歴の表示など、転送の使用方法については、転送の操作をご覧ください。
- クロスクラウドの操作でデータを読み込む方法を学習する。