# Google Cloud Storage Import Integration

Google Cloud Storage用のData Connectorは、GCSバケットに保存されている*.tsvおよび*.csvファイルの内容のインポートを可能にします。Export Integrationについては、[Google Cloud Storage Export Integration](/ja/int/google-cloud-storage-export-integration)を参照してください。

## 前提条件

- Treasure Dataの基本的な知識
- 既存のGoogle Service Account
- Google Developers ConsoleからJSONキーファイルを生成し取得すること。[Generating a service account credential](https://cloud.google.com/storage/docs/authentication#generating-a-private-key)を参照してください。


## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## TD Consoleを使用したGoogle Cloud Storageからのインポート

### 新しい接続の作成

データ接続を設定する際、インテグレーションにアクセスするための認証情報を提供します。Treasure Dataでは、認証を設定してからソース情報を指定します。

1. TD Consoleを開きます。
2. Integrations Hub > Catalogに移動します。
3. Google Cloud Storageを検索して選択します。
![](/assets/image-20191206-003009.5434e471c33eac02c339db73bbed82434413cc8071dba89ed7deb8ddd0aadf75.276f5576.png)
4. 次のダイアログが開きます。
![](/assets/image-20191015-135359.53e904e28e902844ebd25df2bb8175971839b949f891dfca43c844b31eddb9a3.276f5576.png)
5. 新しいGoogle Cloud Storage Connectorを作成します。
6. 以下のパラメータを設定します:


| **パラメータ** | **説明** |
|  --- | --- |
| **Authentication mode** | JSON keyfileを選択します。この方法では、Google Developers Consoleから生成されたJSONキーファイルを使用します。 |
| **JSON Keyfile** | Google Developers Consoleから生成されたJSONキーファイルの内容をこのフィールドにコピー&ペーストします。 |
| **Application Name** | *Treasure Data GCS Output*がデフォルト値です。これはAPIリクエストに関連付けられる任意のクライアント名であるため、デフォルト値(Treasure Data GCS Output)のままにすることができます。 |


### 接続に名前を付ける

1. 接続の名前を入力します。
2. **Done**を選択します。


### Google Cloud StorageアカウントデータをTreasure Dataに転送

認証済み接続を作成すると、自動的にAuthenticationsに移動します。

1. 作成した接続を検索します。
2. **New Source**を選択します。
3. Data Transferフィールドで**Source**の名前を入力します。
4. **Next**をクリックします。


![](/assets/image-20200812-232831.affaea454b73d8f5b11d439a2861c2bebbc1ec0f2064f926499cb200aca2c3fd.276f5576.png)

### Source Table

1. **Next**を選択します。
2. Source Tableダイアログが開きます。以下のパラメータを編集します。


![](/assets/image-20200812-233240.257493d38be492509c623f3cd8c55696fe1c29868b4ece21d6a07df9da44204f.276f5576.png)

| **パラメータ** | **説明** |
|  --- | --- |
| **Bucket** | Google Cloud Storageバケット名(例: *your_bucket_name*) |
| **Path Prefix** | ターゲットキーのプレフィックス。(例: *logs/data_*) |
| **Path Regex** | ファイルパスに一致させるための正規表現。ファイルパスがこのパターンに一致しない場合、そのファイルはスキップされます。(例: *.csv$* # この場合、パスがこのパターンに一致しないファイルはスキップされます。) |
| **Start after path** | *last_path*パラメータを挿入して、最初の実行時にこのパスより前のファイルをスキップします。(例: *logs/data_20170101.csv*) |
| **Incremental** | インクリメンタルローディングを有効にします。インクリメンタルローディングが有効な場合、次回実行の設定差分には*last_path*パラメータが含まれるため、次回実行時にそのパスより前のファイルがスキップされます。それ以外の場合、*last_path*は含まれません。 |


例: CloudFront Log

Amazon CloudFrontは、静的および動的Webコンテンツの配信を高速化するWebサービスです。CloudFrontを設定して、CloudFrontが受信するすべてのユーザーリクエストに関する詳細情報を含むログファイルを作成できます。ロギングを有効にすると、次のようにCloudFrontログファイルを保存できます:


```
[your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-15.a103fd5a.gz]
[your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-15.b2aede4a.gz]
[your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-16.594fa8e6.gz]
[your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-16.d12f42f9.gz]
```

この場合、**Source Table**の設定は次のようになります:

- **Bucket**: your_bucket
- **Path Prefix**: logging/
- **Path Regex**: *.gz$* (必須ではありません)
- **Start after path**: logging/E231A697YXWD39.2017-04-23-15.b2aede4a.gz (2017-04-23-16からログファイルをインポートしたい場合を想定)
- **Incremental**: true (このジョブをスケジュールしたい場合)


### Data Settings

1. **Next**を選択します。
2. **Data Settings**ページが開きます。


オプションで、データ設定を編集するか、ダイアログのこのページをスキップします。

![](/assets/image-20200812-233941.d8cb1d6af994f3003283498c0e8f4fdd0616979d4c642b7f1d77133672b71b99.276f5576.png)

![](/assets/google-cloud-storage-import-integration-2025-02-24-1.50f24e1fb8d74b8ce877136a26f616367cb488af0944ab631593ae069465fa36.276f5576.png)

### Parser

| **パラメータ** | **説明** |
|  --- | --- |
| **Type** | 以下のタイプがサポートされています:   - Avro - CSV - json - Query String |
| **Default timezone** | 値自体にタイムゾーンが含まれていない場合、タイムスタンプカラムのタイムゾーンを変更します。 |
| **Total file count limit** | 読み取るファイルの最大数。(オプション) |
| **Schema Settings** | カラムに名前を付けてデータ型を設定できます。TDは指定されたデータ型として値を解析します。その後、Treasure Dataスキーマに変換して保存します。   - **boolean** - **long** - **timestamp**: Treasure DataではString型としてインポートされます(例: 2017-04-01 00:00:00.000) - **double** - **string** - **json** |


### Data Preview

インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data)を表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. **Next** を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、**Generate Preview** を選択します。
3. データを確認します。


### Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. **Next** を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。
2. **Database** を選択 > **Select an existing** または **Create New Database** を選択します。
3. オプションで、database 名を入力します。
4. **Table** を選択 > **Select an existing** または **Create New Table** を選択します。
5. オプションで、table 名を入力します。
6. データをインポートする方法を選択します。
  - **Append** (デフォルト) - データインポートの結果は table に追加されます。
table が存在しない場合は作成されます。
  - **Always Replace** - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
  - **Replace on New Data** - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。
7. **Timestamp-based Partition Key** 列を選択します。
デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。
8. データストレージの **Timezone** を選択します。
9. **Schedule** の下で、このクエリを実行するタイミングと頻度を選択できます。


#### 一度だけ実行

1. **Off** を選択します。
2. **Scheduling Timezone** を選択します。
3. **Create & Run Now** を選択します。


#### 定期的に繰り返す

1. **On** を選択します。
2. **Schedule** を選択します。UI では、*@hourly*、*@daily*、*@monthly*、またはカスタム *cron* の 4 つのオプションが提供されます。
3. **Delay Transfer** を選択して、実行時間の遅延を追加することもできます。
4. **Scheduling Timezone** を選択します。
5. **Create & Run Now** を選択します。


転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。

## Workflowを使用したGoogle Cloud Storageからのインポート

GCSからデータをインポートするサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/gcs)を参照してください。

## CLI(Toolbelt)経由でのGoogle Cloud Storageからのインポート

コネクタを設定する前に、最新のTD Toolbeltをインストールしてください。

Data Connectorは、"boolean"、"long"、"double"、"string"、"timestamp"タイプの解析をサポートしています。

### Seed Config File (seed.yml)の作成

JSONキーファイルを使用して*seed.yml*を準備します。また、バケット名とターゲットファイル名(または複数ファイルのプレフィックス)を指定する必要があります。


```yaml
in:
  type: gcs
  bucket: sample_bucket
  path_prefix: path/to/sample_file  # path the the *.csv or *.tsv file on your GCS bucket
  auth_method: json_key
  json_keyfile:
    content: |
      {
        "private_key_id": "1234567890",
        "private_key": "-----BEGIN PRIVATE KEY-----\nABCDEF",
        "client_id": "...",
        "client_email": "...",
        "type": "service_account"
      }
out:
  mode: append
```

Data Connector for Google Cloud Storageは、指定されたプレフィックスに一致するすべてのファイルをインポートします。（例: path_prefix: `path/to/sample_` –> `path/to/sample_201501.csv.gz`, `path/to/sample_201502.csv.gz`, …, `path/to/sample_201505.csv.gz`）

### フィールドの推測（load.ymlの生成）

*connector:guess*を使用します。このコマンドは、対象ファイルを自動的に読み取り、ファイル形式をインテリジェントに推測します。


```bash
td connector:guess seed.yml -o load.yml
```

*load.yml*を開くと、ファイル形式、エンコーディング、カラム名、型など、推測されたファイル形式定義が表示されます。


```yaml
in:
  type: gcs
  bucket: sample_bucket
  path_prefix: path/to/sample_file
  auth_method: json_key
  json_keyfile:
    content: |
      {
        "private_key_id": "1234567890",
        "private_key": "-----BEGIN PRIVATE KEY-----\nABCDEF",
        "client_id": "...",
        "client_email": "...",
        "type": "service_account"
      }
  decoders:
  - {type: gzip}
  parser:
    charset: UTF-8
    newline: CRLF
    type: csv
    delimiter: ','
    quote: '"'
    escape: ''
    skip_header_lines: 1
    columns:
    - name: id
      type: long
    - name: company
      type: string
    - name: customer
      type: string
    - name: created_at
      type: timestamp
      format: '%Y-%m-%d %H:%M:%S'
out:
  mode: append
```

*preview*コマンドを使用すると、システムがファイルをどのように解析するかをプレビューできます。


```bash
td connector:preview load.yml
```

guessコマンドは、ソースデータファイルに3行以上、2列以上必要です。これは、ソースデータのサンプル行を使用してカラム定義を推測するためです。

システムがカラム名やカラム型を予期せず検出した場合は、*load.yml*を直接修正して再度プレビューしてください。

previewコマンドは、指定されたバケットから1つのファイルをダウンロードし、そのファイルからの結果を表示します。そのため、previewコマンドとissueコマンドの結果に違いが生じる場合があります。

### ロードジョブの実行

ロードジョブを送信します。データのサイズによっては、数時間かかる場合があります。ユーザーは、データが保存されるデータベースとテーブルを指定する必要があります。

Treasure Dataのストレージは時間によってパーティション分割されているため、*--time-column*オプションを指定することをお勧めします。オプションが指定されていない場合、Data Connectorは最初の*long*または*timestamp*カラムをパーティション分割時間として選択します。*--time-column*で指定するカラムの型は、*long*または*timestamp*型のいずれかである必要があります。

データに時間カラムがない場合は、*add_time*フィルターオプションを使用して追加できます。詳細については、[add_timeフィルタープラグイン](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function)を参照してください。


```bash
td connector:issue load.yml --database td_sample_db --table td_sample_table   --time-column created_at
```

前述のコマンドは、*database(td_sample_db)*と*table(td_sample_table)*がすでに作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは成功しないため、データベースとテーブルを手動で作成するか、*td connector:issue*コマンドで*--auto-create-table*オプションを使用してデータベースとテーブルを自動作成してください。


```bash
td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column created_at --auto-create-table
```

Data Connectorはサーバー側でレコードをソートしません。時間ベースのパーティション分割を効果的に使用するには、ファイル内のレコードを事前にソートしてください。

*time*というフィールドがある場合は、*--time-column*オプションを指定する必要はありません。


```bash
td connector:issue load.yml --database td_sample_db --table td_sample_table
```

### スケジュール実行

増分Google Cloud Storageファイルインポートのために、定期的なData Connector実行をスケジュールできます。TDはスケジューラーを慎重に管理して、高可用性を確保します。この機能を使用することで、ローカルデータセンターで*cron*デーモンを使用する必要がなくなります。

スケジュールインポートの場合、Data Connector for Google Cloud Storageは、最初に指定されたプレフィックスに一致するすべてのファイルをインポートし（例: path_prefix: `path/to/sample_` –> `path/to/sample_201501.csv.gz`, `path/to/sample_201502.csv.gz`, …, `path/to/sample_201505.csv.gz`）、次回の実行のために最後のパス（`path/to/sample_201505.csv.gz`）を記憶します。

2回目以降の実行では、アルファベット順（辞書順）で最後のパスの後に来るファイルのみをインポートします。（`path/to/sample_201506.csv.gz`, …）

### スケジュールの作成

新しいスケジュールは、*td connector:create*コマンドを使用して作成できます。スケジュールの名前、cron形式のスケジュール、データが保存されるデータベースとテーブル、およびData Connector設定ファイルが必要です。


```bash
td connector:create daily_import "10 0 * * *" td_sample_db td_sample_table load.yml
```

Treasure Dataのストレージは時間によってパーティション分割されているため、*--time-column*オプションを指定することもお勧めします。


```bash
td connector:create daily_import "10 0 * * *" td_sample_db td_sample_table load.yml --time-column created_at
```

`cron`パラメータは、3つの特別なオプションも受け入れます：`@hourly`、`@daily`、`@monthly`。デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。-tまたは--timezoneオプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone`オプションは、'Asia/Tokyo'、'America/Los_Angeles'などの拡張タイムゾーン形式のみをサポートしています。PST、CSTなどのタイムゾーン略語は*サポートされておらず*、予期しないスケジュールになる可能性があります。

### スケジュールの一覧表示

*td connector:list*コマンドを実行すると、現在スケジュールされているエントリのリストを確認できます。


```
$ td connector:list
```