# Google Cloud Storage Import V2 Integration

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

## 前提条件

- Treasure Dataの基礎知識（[TD Toolbelt](https://toolbelt.treasuredata.com/)を含む）
- 特定の権限を持つGoogle Cloud Platformアカウント


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

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

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[IP Addresses for Integrations](/apis/endpoints/ip-addresses-integrations-result-workers)

### Google JSON認証情報の取得

Google Cloud Storageとの統合は、サーバー間API認証に基づいています。

JSON認証情報の生成に使用するService Accountには、Storage Object Userの権限が必要です。

1. Google Developer Consoleにアクセスします。
2. 左側のメニューでAPIs & Servicesの下のCredentialsを選択します。


![](/assets/gcs_v2_2.d96a9f7dec347056740ae90fc6866fbc6c78f9d9b5d1a999dc0a3663452e4f1f.01768ec3.png)

1. Create credentialsを選択し、Service accountを選択します。


![](/assets/gcs_v2_3.6a564dc9b561061e0b5fa0f783c196f3585cd3309c397bd56f2e713dce828210.01768ec3.png)

1. PermissionsからStorage Object User Roleを追加します。


### Application Default Credentials (ADC) Keyfileの取得

1. IAM & Admin / Workload Identity Poolsの下でcreate poolを選択するか、既存のPoolを選択します。


![](/assets/gcs_v2_5.b29c6dbd8144a5c1208953a7129b820e778c43284075c479a9ebd04dc834d2a8.01768ec3.png)
![](/assets/gcs_v2_4.8c6962bc70473778e721ddf4e7e6ae5c7c2e9cb26bc8510be8f55a328670d354.01768ec3.png)

1. アカウントID **523683666290** でAWSプロバイダーを追加します。


![](/assets/gcs_v2_6.3e3283ca2462b5e616ca1ffa6d5b2cc5a76b0b6327e096428c01db5d5cb40652.01768ec3.png)

1. Configure provider attributesからAdd mappingを選択します。名前に **attribute.account**、値に **assertion.account** を持つ属性を追加し、Saveします。
2. Workload Identity Poolsから作成したプールを選択し、Connected service accountsからDownload configを選択します。
![](/assets/gcs_v2_7.9399e7b93f7f9b6239278e8f87af939fc11f0fd1c06199569a5394340e6090c3.01768ec3.png)
3. アカウントID **523683666290** 用に作成したAWSプロバイダーを選択し、Downloadを選択して設定ファイル（Application default credential keyfile）を保存します。


### AWSプロバイダーに宛先バケットへのアクセス権限を付与

1. バケットリストから宛先バケットを選択し、permissionsタブを選択します。
2. Grant accessを選択し、Principals値に **principalSet://iam.googleapis.com/projects/{PROJECT_NUMBER}/locations/global/workloadIdentityPools/{POOL_ID}/attribute.account/523683666290** を追加し、ロールをStorage Object Userに設定します。


![](/assets/gcs_v2_10.2c69560a43e6aa632bf83ee8b04441e42c3fbd8926f1c820cfc9c0f44116736a.01768ec3.png)
![](/assets/gcs_v2_11.61fd4999a78444d32248ae89c67881555f3005de4825f1cb24b01b129f8b35c1.01768ec3.png)

### 新しい認証の作成

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

1. **Treasure コンソール**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. Google Cloud Storage V2を検索して選択します。


![](/assets/gcs_v2_12.4c53928180751cb2fe12c8abe6bbd276c87d3670b1bb12c494840f482ad9caa7.01768ec3.png)

1. **Create Authentication**を選択します。
2. Authentication Methodを選択し、認証情報を入力します。


![](/assets/gcs_v2_13.cb9ab21dd436bcf45f8846088a5ffa3e8ef4b4c42592817d868907667d46bf4c.01768ec3.png)

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


### Google Cloud StorageデータをTreasure Dataに転送

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

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


![](/assets/gcs_v2_14.12ab6edfe6657b89779d7b2982d231fce69441119e7b234f7e29c32899386dbf.01768ec3.png)

### Source Table

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


![](/assets/gcs_v2_15.cc6c89ab4619ad878d7d9426681bb8f9aa6f6dce0154f6cdb7c4f4caa99bf35b.01768ec3.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** | インクリメンタルローディングを有効にします。インクリメンタルローディングが有効な場合、次回の実行のconfig diffに *last_path* パラメータが含まれ、次回の実行でこのパスより前のファイルをスキップします。無効の場合、*last_path* は含まれません。 |


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

- **Bucket**: your_bucket
- **Path Prefix**: path/to/name
- **Path Regex**: *.csv$* （必須ではありません）
- **Start after path**: path/to/name1.csv（name1.csv以降のファイルをインポートしたい場合）
- **Incremental**: true（このジョブをスケジュール設定したい場合）


### Data Settings

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


必要に応じてデータ設定を編集するか、このページをスキップします。

![](/assets/gcs_v2_16.d8cb1d6af994f3003283498c0e8f4fdd0616979d4c642b7f1d77133672b71b99.01768ec3.png)

![](/assets/gcs_v2_17.50f24e1fb8d74b8ce877136a26f616367cb488af0944ab631593ae069465fa36.01768ec3.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)の作成

*seed.yml* をJSON keyfileで準備します。バケット名とターゲットファイル名（または複数ファイルの場合はプレフィックス）も指定する必要があります。

Service Account認証の場合


```yaml
in:
  type: gcs_v2
  bucket: sample_bucket
  path_prefix: path/to/sample_file  # GCSバケット上の*.csvまたは*.tsvファイルへのパス
  path_match_pattern: "*.csv.gz$"
  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
```

Workload Identity Federation認証の場合


```yaml
in:
  type: gcs_v2
  bucket: sample_bucket
  path_prefix: path/to/sample_file  # GCSバケット上の*.csvまたは*.tsvファイルへのパス
  path_match_pattern: "*.csv.gz$"
  auth_method: wif
  adc_keyfile:
    content: |
      {
        ..........
      }
out:
  mode: append
```

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

### Guess Fields (load.ymlの生成)

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


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

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


```yaml
in:
  type: gcs_v2
  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*タイプである必要があります。

データにtimeカラムがない場合は、*add_time*フィルターオプションを使用して追加できます。詳細は[add_time filter plugin](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*デーモンを使用する必要がなくなります。

スケジュールされたインポートの場合、Google Cloud Storage用のData Connectorは、指定されたプレフィックスにマッチするすべてのファイル（例：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`パラメータは、`@hourly`、`@daily`、`@monthly`の3つの特別なオプションも受け付けます。デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。-tまたは--timezoneオプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone`オプションは、'Asia/Tokyo'、'America/Los_Angeles'などの拡張タイムゾーン形式のみをサポートします。PST、CSTなどのタイムゾーンの略語は*サポートされておらず*、予期しないスケジュールにつながる可能性があります。

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

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


```
$ td connector:list
```