# Yotpo Import Integration

Yotpo Reviewsは、ビジネスを支援するレビュープラットフォームです:

- Yotpo widgetをインストールすることで、Shopify、BigCommerce、WooCommerce、その他のeCommerceウェブサイトなど、多くのソースから顧客レビューを収集および分析します。
- Facebook、Instagram、Google Shopping Reviews、SNSなどのSNS（Simple Notification Service）からレビューを収集および分析します。
- 特定の条件に基づいて、顧客に自動的にレビューリクエストを送信します。


このインテグレーションにより、YotpoからTreasure Data™プラットフォームに収集された顧客レビューを取り込むことができます。

## 前提条件

- Treasure Data™の基本知識。
- Yotpoプラットフォームの基本知識


## 要件と制限事項

- Yotpo App KeyとApp Secret Keyを取得してください。[https://support.yotpo.com/en/article/finding-your-yotpo-app-key-and-secret-key](https://support.yotpo.com/en/article/finding-your-yotpo-app-key-and-secret-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経由でYotpoからインポート

### 認証の作成

最初のタスクは、資格情報のセットを使用して新しい認証を作成することです。

1. **Integrations Hub**を選択します。
2. **Catalog**を選択します。


![](/assets/image2021-9-30_14-38-2.ca92fa4ab9277dca95973c6bd413fc662a3f0d04b57d58f7a8c952a29f28bbec.82836e02.png)

1. カタログで目的のインテグレーションを検索し、マウスをアイコンの上に置いて**Create Authentication**を選択します。


![](/assets/image2021-9-30_14-42-0.d6a5ad453f9fa98b4336af9506dadbd04ea44299e2f9af7fd760f75ac68e3f88.82836e02.png)

1. **Credentials**タブが選択されていることを確認し、インテグレーションの資格情報を入力します。


![](/assets/image2022-8-26_16-50-49.e4f4475d23608a4c563ee259f2d710e0029b4329ce5d40746fcfacdee821762b.82836e02.png)

#### **新しい認証フィールド**

| パラメータ | 説明 |
|  --- | --- |
| App Key | アプリケーションキー |
| App Secret | アプリケーションシークレットキー |


1. 認証の名前を入力し、**Done**を選択します。


### ソースの作成

1. TD Consoleを開きます。
2. **Integrations Hub** > **Authentications**に移動します。
3. 新しい認証を見つけて、**New Source**を選択します。


### 接続の作成

ソースに対して次の表を完成させます。

| パラメータ | 説明 |
|  --- | --- |
| Data Transfer Name | 転送の名前を定義できます。 |
| Authentication | 転送に使用される認証名。 |


1. Data Transfer Nameフィールドにソース名を入力します。
2. **Next**を選択します。


**Create Source**ページが表示され、**Source Table**タブが選択されています。

### ソーステーブルの識別

![](/assets/image2022-8-26_16-51-40.08895160bf0bb3c93c3342fdcddd7329511879ce4e1acb6af23753041ac8ce25.82836e02.png)

| パラメータ | 説明 |
|  --- | --- |
| Source | インポートするデータタイプ:   - Reviews |
| Include Unpublished Reviews | 選択した場合、公開済みと未公開の両方のレビューをインポートします。それ以外の場合は、公開済みのレビューのみをインポートします。 |
| Incremental Loading | 繰り返し実行する場合、前回のインポート以降の新しいデータのみをインポートしようとします。 |
| Last Updated Time | この時刻以降のデータをインポートします。CLI構成の場合、ナノ秒単位まで正確なRFC3339 UTC "Zulu"形式のタイムスタンプが必要です（例: "2022-08-22T15:01:23Z"）。 |


**Next**をクリックします。

### データ設定の定義

![](/assets/image2022-8-26_16-53-3.45aadb719e07b85dca25ebd90d9531e079cdd4250f4e2569ea244009f189aa18.82836e02.png)

| パラメータ | 説明 |
|  --- | --- |
| Max Retry Count per API Call | デフォルト5、最小0、最大10 |
| Initial Retry Interval per API Call | 秒単位、デフォルト1、最小1、最大300 |
| Max Retry Interval per API Call | 秒単位、デフォルト120、最小1、最大300 |
| Max Connection Timeout per API Call | 秒単位、デフォルト300、最小30、最大300 |


**Next**をクリックします。

### 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** で転送の結果を確認できます。

## ワークフローを使用してYotpoからインポート

ワークフローのtd_load>オペレーターを使用して、Yotpoからデータをインポートできます。既にSOURCEを作成している場合は実行できます。SOURCEを作成したくない場合は、ymlファイルを使用してインポートできます。

### Sourceを使用する

1. Sourceを特定します。
2. 一意のIDを取得するには、Sourceリストを開き、製品でフィルタリングします。
3. メニューを開き、「Copy Unique ID」をクリックします。


![](/assets/image2021-10-12_12-26-58.09d9b84b0f1f752c7c95b0bc1c2d8e8b7302e5b91c6a3cb5f01309dadf53a604.82836e02.png)

1. td_load>オペレーターを使用してワークフロータスクを定義します。



```yaml
+load:
  td_load>: unique_id_of_your_source
  database: ${td.dest_db}
  table: ${td.dest_table}
```

1. ワークフローを実行します。


### Yamlファイルを使用する

1. ymlファイルを特定します。ymlファイルを作成する必要がある場合は、参考として[Amazon S3 Import Integration Using CLI](/ja/int/amazon-s3-import-integration-v2#cli-configurations)を確認してください。
2. td_load>オペレーターを使用してワークフロータスクを定義します。



```yaml
+load:
  td_load>: config/daily_load.yml
  database: ${td.dest_db}
  table: ${td.dest_table}
```

1. ワークフローを実行します。


#### パラメータリファレンス

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | コネクターインポートタイプ | string | yotpo | yes |
| data_source | インポートするデータタイプ | string | reviews |  |
| include_unpublished_reviews | `選択した場合、公開済みおよび未公開のレビューの両方をインポートします。それ以外の場合は、公開済みのレビューのみをインポートします` | boolean | false |  |
| incremental | `繰り返し実行する場合、前回のインポート以降の新しいデータのみをインポートしようとします` | boolean | false |  |
| last_updated_time | `この時刻以降のデータをインポートします。例: "2022-08-22T15:01:23Z"` | datetime |  |  |
| retry_limit | `API呼び出しごとの最大リトライ回数` | integer | 5 |  |
| initial_retry_wait | `API呼び出しごとの初期リトライ間隔(秒単位)` | integer | 1 |  |
| max_retry_wait | `API呼び出しごとの最大リトライ間隔(秒単位)` | integer | 120 |  |
| connection_timeout | `API呼び出しごとの最大接続タイムアウト(秒単位)` | integer | 300 |  |


### サンプルワークフローコード

サンプルワークフローコードについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3)をご覧ください。

## CLI(Toolbelt)を使用してYotpoからインポート

コネクターを設定する前に、最新の[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールしてください。

### load.ymlを作成


```yaml
in:
  type: yotpo
  app_key: xxxx
  app_secret: xxxxxx
  data_source: reviews
  incremental: true
  last_updated_time: '2022-08-23T11:26:32Z'
  include_unpublished_reviews: true
  retry_limit: 1
  initial_retry_wait: 2
  max_retry_wait: 123
  connection_timeout: 234
```

データをプレビューするには、*td connector:preview* コマンドを使用します。


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

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

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

また、Treasure Data のストレージは時間でパーティション分割されているため（[データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)を参照）、*--time-column* オプションを指定することをお勧めします。このオプションを指定しない場合、データコネクターは最初の *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
```

connector:issue コマンドは、*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
```

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

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


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

### インポートモード

load.yml ファイルの out セクションでファイルのインポートモードを指定できます。out: セクションは、Treasure Data テーブルへのデータのインポート方法を制御します。たとえば、データを追加するか、Treasure Data の既存のテーブルのデータを置き換えるかを選択できます。

| **モード** | **説明** | **例** |
|  --- | --- | --- |
| Append | レコードは対象テーブルに追加されます。 | in:    ...  out:    mode: append |
| Always Replace | 対象テーブルのデータを置き換えます。対象テーブルに対して手動で行われたスキーマの変更はそのまま残ります。 | in:    ...  out:    mode: replace |
| Replace on new data | インポートする新しいデータがある場合にのみ、対象テーブルのデータを置き換えます。 | in:    ...  out:    mode: replace_on_new_data |


### 実行のスケジューリング

増分ファイルインポート用に定期的なデータコネクターの実行をスケジュールできます。Treasure Data は、高可用性を確保するためにスケジューラーを慎重に設定しています。

スケジュールされたインポートでは、指定されたプレフィックスに一致するすべてのファイルと、以下のいずれかのフィールドを条件としてインポートできます：

- use_modified_time が無効になっている場合、最後のパスが次の実行のために保存されます。2回目以降の実行では、コネクターはアルファベット順で最後のパスの後にあるファイルのみをインポートします。
- それ以外の場合、ジョブが実行された時刻が次の実行のために保存されます。2回目以降の実行では、コネクターはアルファベット順でその実行時刻以降に変更されたファイルのみをインポートします。


### TD Toolbelt を使用したスケジュールの作成

*td connector:create* コマンドを使用して新しいスケジュールを作成できます。


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

Treasure Data のストレージは時間でパーティション分割されているため（[データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)も参照）、*--time-column* オプションを指定することをお勧めします。


```
$ 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 などのタイムゾーンの略語はサポートされて*おらず*、予期しないスケジュールにつながる可能性があります。