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 のバケット部分はパラメータ化できません。
Amazon S3 からの転送は、常に WRITE_APPEND 設定によってトリガーされ、データが宛先テーブルに追加されます。詳細については、読み込みジョブ構成の configuration.load.writeDisposition をご覧ください。
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

Cloud Console の BigQuery ページに移動します。

[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 のいずれかを選択できます。
- [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 オプションを入力します。
- （省略可）[通知オプション] セクションで、次の操作を行います。
  - 切り替えボタンをクリックしてメール通知を有効にします。このオプションを有効にすると、転送の実行が失敗した場合、転送管理者にメール通知が送信されます。
  - [Pub/Sub トピックを選択してください] で、トピック名を選択するか、[トピックを作成する] をクリックしてトピックを作成します。このオプションで、Pub/Sub の転送実行通知を構成します。
[保存] をクリックします。

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 です。
- 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_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 リソースのインスタンスを指定します。

Java

GitHub で表示フィードバック

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

データのクエリ

データが 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 に読み込まれません。転送ログは次のようになります。

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 から転送されたファイルが 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 の概要をご覧ください。
転送構成に関する情報の取得、転送構成の一覧表示、転送の実行履歴の表示など、転送の使用方法については、転送の操作をご覧ください。