Amazon S3 転送

BigQuery Data Transfer Service for Amazon S3 を使用すると、Amazon S3 から BigQuery への定期的な読み込みジョブを自動的にスケジュールし、管理できます。

始める前に

Amazon S3 転送を作成する前に:

BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
従来の BigQuery ウェブ UI を使用して転送を作成する場合は、権限ウィンドウが表示されるように、ブラウザで bigquery.cloud.google.com からのポップアップを許可します。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 のバケット部分はパラメータ化できません。
Amazon S3 からの転送は、常に WRITE_APPEND 設定によってトリガーされ、データが宛先テーブルに追加されます。詳細については、読み込みジョブ構成の configuration.load.writeDisposition をご覧ください。
Amazon S3 のソースデータの形式によっては、追加の制限が適用される場合があります。詳細情報

必要な権限

Amazon S3 転送を作成する前に:

転送を作成するユーザーに、BigQuery で必要な次の権限が付与されていることを確認します。
- bigquery.transfers.update（転送を作成する権限）
- bigquery.datasets.update（抽出先データセットに対する権限）
bigquery.transfers.update 権限と bigquery.datasets.update 権限は、事前定義された IAM のロール bigquery.admin に含まれています。BigQuery Data Transfer Service での IAM ロールの詳細については、アクセス制御のリファレンスをご覧ください。
転送を有効にするために必要な権限が構成されたことを確認するには、Amazon S3 のドキュメントをご覧ください。少なくとも、Amazon S3 ソースデータには AWS 管理ポリシー AmazonS3ReadOnlyAccess が適用されている必要があります。

Amazon S3 データ転送の設定

Amazon S3 データ転送を作成するには:

Console

Cloud Console の BigQuery ウェブ UI に移動します。

Cloud Console に移動
[転送] をクリックします。
[転送を作成] をクリックします。
[転送の作成] ページで、次の操作を行います。
- [ソースタイプ] セクションの [ソース] で、[Amazon S3] を選択します。
- [転送構成名] セクションの [表示名] に、転送名（例: My Transfer）を入力します。転送名には、後で修正が必要になった場合に簡単に識別できる任意の名前を使用できます。
- [スケジュールオプション] セクションで、[スケジュール] をデフォルト値（[すぐに開始可能]）のままにするか、[設定した時間に開始] をクリックします。
  - [繰り返しの頻度] で、転送を実行する頻度のオプションを選択します。次のオプションがあります。
    - 毎日（デフォルト）
    - 毎週
    - 毎月
    - カスタム
    - オンデマンド
    [毎日] 以外のオプションを選択した場合は、追加のオプションが利用可能です。たとえば、[毎週] を選択した場合、曜日を選択するためのオプションが表示されます。
  - [開始日と実行時間] に、転送を開始する日付と時刻を入力します。[すぐに開始可能] を選択した場合、このオプションは無効になります。
- [転送先の設定] セクションの [宛先データセット] で、データを保存するために作成したデータセットを選択します。
- [データソースの詳細] セクションで、次の操作を行います。
  - [宛先テーブル] に、BigQuery でデータを保存するために作成したテーブルの名前を入力します。宛先テーブルの名前では、パラメータがサポートされています。
  - [Amazon S3 URI] に、s3://mybucket/myfolder/... の形式で URL を入力します。URI でもパラメータがサポートされています。
  - [Access key ID] に、アクセスキー ID を入力します。
  - [Secret access key] に、シークレットアクセスキーを入力します。
  - [File format] で、データ形式を選択します。JSON（改行区切り）、CSV、Avro、Parquet、ORC のいずれかを選択できます。
- [転送オプション] セクションの [許可されているエラー数] に、無視できる不良レコードの最大数にあたる整数値を入力します。
- ファイル形式として CSV または JSON を選択した場合、スキーマに適合しない値を含んだ行を許容するには、[JSON, CSV] セクションで [不明な値を無視する] をオンにします。こうすると、不明な値は無視されるようになります。CSV ファイルでは、行の末尾の余分な値も無視されます。
- ファイル形式として CSV を選択した場合は、[CSV] セクションでデータを読み込むための追加の CSV オプションを入力します。
- （省略可）[通知オプション] セクションで、次の操作を行います。
  - 切り替えボタンをクリックしてメール通知を有効にします。このオプションを有効にすると、転送の実行が失敗した場合、転送管理者にメール通知が送信されます。
  - [Pub/Sub トピックを選択してください] で、トピック名を選択するか、[トピックを作成する] をクリックしてトピックを作成します。このオプションで、Pub/Sub の転送実行通知を構成します。
[保存] をクリックします。

従来の UI

BigQuery ウェブ UI に移動します。

BigQuery ウェブ UI に移動
[Transfers] をクリックします。
[Add Transfer] をクリックします。
[New Transfer] ページで次の操作を行います。
- [Source] で [Amazon S3] を選択します。
- [Display name] に転送名（例: My Transfer）を入力します。表示名には、後で修正が必要になった場合に簡単に識別できる任意の名前を使用できます。
- （省略可）[Schedule] では、デフォルト値の [Daily]（作成時間から 24 時間ごと）のままにするか、[Edit] をクリックして時間を変更します。間隔を [Weekly]、[Monthly]、[Custom] に変更することもできます。[Custom] を選択すると、every 12 hours のような Cron と同様の時間を指定するよう求められます。最短許容時間は 12 時間です。他の有効な API 値については、TransferConfig の schedule フィールドをご覧ください。
- [Destination dataset] で、該当するデータセットを選択します。
- [Destination table] に宛先テーブルの名前を入力します。宛先テーブルは、テーブルの命名規則に従う必要があります。宛先テーブル名でもパラメータがサポートされています。
- [Amazon S3 URI] に、Amazon S3 URI を入力します。ワイルドカードとパラメータがサポートされています。
- [Access key ID] に、アクセスキー ID を入力します。
- [Secret access key] に、シークレットアクセスキーを入力します。
- [File format] で、データ形式を選択します。JSON（改行区切り）、CSV、Avro、Parquet、ORC のいずれかを選択できます。
- [Transfer Options - All Formats] セクションでは、以下のように設定します。
  - [Number of errors allowed] には、BigQuery がジョブの実行中に無視できる不良レコードの最大数を入力します。不良レコード数がこの値を超えると、ジョブ結果で「invalid」が返されてジョブが失敗します。デフォルト値は 0 です。
- ファイル形式として CSV または JSON を選択した場合、[Transfer Options - JSON, CSV] セクションでは、以下のように設定します。
  - 転送で宛先テーブルのスキーマに適合しないデータが削除されるようにする場合は、[Ignore unknown values] をオンにします。
- ファイル形式として CSV を選択した場合、[Transfer Options - CSV] セクションでは、以下のように設定します。
  - [Field delimiter] に、フィールドを区切る文字を入力します。デフォルト値はカンマ（,）です。
  - [Header rows to skip] に、インポートの対象外にするソースファイル内のヘッダー行の数を入力します。デフォルト値は 0 です。
  - 引用符で囲まれたフィールド内で改行を許可するには、[Allow quoted newlines] をオンにします。
  - NULLABLE 列がない行を転送できるようにする場合は、[Allow jagged rows] をオンにします。
  注: 詳細については、CSV 専用オプションをご覧ください。
- （省略可）[Advanced] セクションを展開し、転送の実行通知を構成します。
- [Cloud Pub/Sub topic] に、Cloud Pub/Sub トピックの名前（例: projects/myproject/topics/mytopic）を入力します。
- [メール通知を送信する] をオンにして、転送の実行が失敗した場合のメール通知を許可します。
[追加] をクリックします。

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 です。
- max_bad_records: 省略可。許可する不良レコードの数を指定します。デフォルトは 0 です。
- 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_template の値に 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_template":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--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 リソースのインスタンスを指定します。

データのクエリ

データが BigQuery に転送されると、取り込み時間パーティション分割テーブルにそのデータが書き込まれます。詳細については、パーティション分割テーブルの概要をご覧ください。

自動生成されたビューを使用せずに、テーブルでクエリを直接実行する場合は、そのクエリで _PARTITIONTIME 疑似列を使用する必要があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

プレフィックスマッチングまたはワイルドカードマッチングの影響

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 ユーザーに次の操作を行う権限があることを確認します。 Amazon S3 バケットの一覧を表示するバケットのロケーションを取得するバケット内のオブジェクトを読み取る
サーバーがオブジェクトのアップロードを初期化できません。InvalidObjectState: オブジェクトのストレージクラスには無効なオペレーションですソース S3 バケットの場所を取得できませんでした。詳細: このオブジェクトへのアクセスはすべて無効です	Amazon Glacier にアーカイブされているすべてのオブジェクトを復元します。Amazon Glacier にアーカイブされている Amazon S3 のオブジェクトには、復元するまでアクセスできません。
このオブジェクトへのアクセスはすべて無効です。	転送構成で Amazon S3 URI が正しく設定されていることを確認します。

Amazon S3 転送量の上限エラー

エラー	推奨される対応
転送中のファイルの数が上限の 10,000 を超えています。	Amazon S3 URI に含まれるワイルドカードの数を 1 つだけに減らすことが可能かどうかを評価します。可能であれば、新しい転送構成で再試行します。転送実行ごとの最大ファイル数が増加します。転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。
転送中のファイルのサイズが 16,492,674,416,640 バイトの上限を超えています。	転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。

エラー

推奨される対応

転送中のファイルの数が上限の 10,000 を超えています。

Amazon S3 URI に含まれるワイルドカードの数を 1 つだけに減らすことが可能かどうかを評価します。可能であれば、新しい転送構成で再試行します。転送実行ごとの最大ファイル数が増加します。

転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。

転送中のファイルのサイズが 16,492,674,416,640 バイトの上限を超えています。

転送構成を複数の転送構成に分割し、それぞれの構成でソースデータの一部を転送できるかどうかを評価します。

一般的な問題

エラー推奨される対応

Amazon S3 から転送されたファイルが BigQuery に読み込まれません。転送ログは次のようになります。

Amazon S3 から Google Cloud へのデータの移動完了: <NNN> オブジェクトを移動しました。
一致する新しいファイルはありません <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 から転送されたファイルが BigQuery に読み込まれません。転送ログは次のようになります。 Amazon S3 から Google Cloud へのデータの移動完了: <`NNN`> オブジェクトを移動しました。一致する新しいファイルはありません <`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 の概要をご覧ください。
転送構成に関する情報の取得、転送構成の一覧表示、転送の実行履歴の表示など、転送の使用方法については、転送の操作をご覧ください。