# Brandwatch Import Integration

このデータコネクタを使用すると、Brandwatch の Mention オブジェクトを Treasure Data にインポートできます。

# 制限事項

**API の制限**。*クエリ*または*クエリグループ*に大量のメンション(例えば、5000 件以上のメンション)が含まれる場合、すべてのメンションを取得するために最大 50 件のリクエストが必要になります。*page size* パラメータを使用してリクエストを管理してください。

以下のトピックに進みます:

# 前提条件

- Treasure Data アカウントの基本的な知識とアクセス権
- Brandwatch アカウントの基本的な知識とアクセス権


# TD Console の使用

## 新しい接続の作成

Integrations Hub > Catalog に移動します。Brandwatch を検索して選択します。

![](/assets/brandwatchtile.dcb235ba78d6822d576cab774bde1ece2be3de5afbac8496cad0e08e44bab557.4ea22b15.png)

ダイアログが開きます。

Brandwatch のユーザー名とパスワード情報を入力し、**Continue** を選択して接続に名前を付けます:

![](/assets/brandwatchauthen.e3bd0b36123fb19225fc68859210406d5a32cfaf7305a2136539b684e5fd00e8.4ea22b15.png)

## 新しいソースの作成

接続を作成すると、自動的に Integrations Hub > Catalog に戻ります。作成した接続を探して **New Source** を選択します。

ダイアログが開きます。詳細を入力して **Next** を選択します。

![](/assets/brandwatchsource.d787724b181cfe8aadf9ae8edc1d450987181d03ffd89cdeaaac85af94c764ab.4ea22b15.png)

次に、以下のようなダイアログでデータのプレビューが表示されます。変更を加えるには、**Advanced Settings** を選択してエラーのスキップやレート制限などのオプションを変更できます。それ以外の場合は、**Next** を選択します。

データの転送先となる既存のデータベースとテーブルを選択するか、新しく作成します。

Schedule タブでは、1 回限りの転送を指定するか、自動的に繰り返される転送をスケジュールすることができます。Once now を選択した場合は、**Start Transfer** を選択します。Repeat… を選択した場合は、スケジュールオプションを指定してから **Schedule Transfer** を選択します。

転送が実行されると、**Data Workbench** > **Databases** で転送結果を確認できます。対応するジョブが Jobs セクションに表示されます。

これでデータの分析を開始する準備が整いました。

# コマンドラインの使用

## 'td' コマンド v0.11.9 以降のインストール

最新の [TD Toolbelt](https://toolbelt.treasuredata.com/) をインストールできます。


```
$ td --version
0.15.8
```

## 設定ファイルの作成

Brandwatch の認証情報と転送情報を含む設定ファイル(例: *load.yml*)を次の例のように準備します。


```yaml
in:
  type: brandwatch
  username: xxxxxxxxxx
  password: xxxxxxxxxx
  project_name: xxx
  query_name: xxx
  from_date: yyyy-MM-dd'T'hh:mm:ss.SSS'Z'
  to_date: yyyy-MM-dd'T'hh:mm:ss.SSS'Z'
out:
  mode: replace
```

この例は、クエリを実行して Brandwatch のメンションをダンプする方法を示しています。クエリ以外に、メンションを取得するための別のオプション *query_group* もあります:


```yaml
in:
  type: brandwatch
  username: xxxxxxxxxx
  password: xxxxxxxxxx
  project_name: xxx
  query_group_name: xxx
  from_date: yyyy-MM-dd'T'hh:mm:ss.SSS'Z'
  to_date: yyyy-MM-dd'T'hh:mm:ss.SSS'Z'
out:
  mode: replace
```

## 設定

- *username*: Brandwatchアカウントのユーザー名（string、必須）
- *password*: Brandwatchアカウントのパスワード（string、必須）
- *project_name*: すべてのクエリ、クエリグループ、メンションなどが属するBrandwatchプロジェクト（string、必須）
- *query_name*: メンションを取得するために実行されるBrandwatchクエリ名（string、オプション）
- *query_group_name*: メンションを取得するために実行されるBrandwatchクエリグループ名（string、オプション）
  - **注意:** *query_name* または *query_group_name* のいずれかが存在する必要があり、両方が同時に存在してはいけません
- *from_date*: レコードを取得する開始日時を指定します（日付形式: *yyyy-MM-dd'T'hh:mm:ss.SSS'Z'*）（string、必須、境界値を含む）
- *to_date*: レコードを取得する終了日時を指定します（日付形式: *yyyy-MM-dd'T'hh:mm:ss.SSS'Z'*）（string、必須、境界値を含まない）
- *retry_initial_wait_msec*: Brandwatch APIを呼び出す各リトライロジックの初期待機時間（ミリ秒単位）を提供するパラメータ
- *max_retry_wait_msec*: Brandwatch APIを呼び出す各リトライの最大待機時間（ミリ秒単位）を提供するパラメータ（int、オプション）
- *retry_limit*: Brandwatch APIを呼び出す試行回数を提供するパラメータ（int、オプション）
- *page_size*: API呼び出しごとに取得されるメンション数を提供するパラメータ
  - **注意**: このパラメータは、*query* または *query group* に大量のメンションが含まれている場合にAPI制限を克服するのに非常に役立ちます。例えば、*query X* に合計5000件のメンションが含まれている場合、デフォルト設定ではすべてのメンションを取得するのに最大50回のリクエストが必要になり、リクエスト数が多いほどAPI制限に達する可能性が高くなります。*page_size* を *200* に変更すると、前述のクエリでは最大25回のリクエストで済みます


## インポートするデータのプレビュー（オプション）

*td connector:preview* コマンドを使用して、インポートされるデータをプレビューできます。


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

## ロードジョブの実行

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

Treasure Dataのストレージは時間によってパーティション化されているため、*--time-column* オプションを指定することをお勧めします（[data partitioning](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)も参照してください）。オプションが指定されていない場合、データコネクタは最初の *long* または *timestamp* カラムをパーティショニング時間として選択します。*--time-column* で指定されたカラムのタイプは、*long* または *timestamp* タイプのいずれかでなければなりません。

データに時間カラムがない場合は、*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 modifieddate
```

上記のコマンドは、すでに *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 modifieddate --auto-create-table
```

"--time-column"オプションで時間形式のカラムを「パーティショニングキー」に割り当てることができます。

## スケジュール実行

定期的なBrandwatchインポートのために、定期的なデータコネクタの実行をスケジュールできます。高可用性を確保するために、スケジューラは慎重に設定されています。この機能を使用することで、ローカルデータセンターに *cron* デーモンを配置する必要がなくなります。

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


```
$ td connector:create \
    daily_Brandwatch_import \
    "9 0 * * *" \
    td_sample_db \
    td_sample_table \
    load.yml
```

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

## スケジュールのリスト表示

*td connector:list* で、スケジュールされたエントリのリストを確認できます。


```
$ td connector:list
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
| Name                    | Cron        | Timezone | Delay | Database     | Table           | Config                       |
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
| daily_brandwatch_import | 9 0 * * *   | UTC      | 0     | td_sample_db | td_sample_table | {"type"=>"brandwatch", ... } |
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
```

## スケジュールの設定と履歴を表示する

*td connector:show* はスケジュールエントリの実行設定を表示します。


```
% td connector:show daily_brandwatch_import
Name     : daily_brandwatch_import
Cron     : 9 0 * * *
Timezone : UTC
Delay    : 0
Database : td_sample_db
Table    : td_sample_table
```

*td connector:history* はスケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、*td job jobid* を使用します。


```bash
td connector:history daily_salesforce_marketing_cloud_import
```

## スケジュールを削除する

*td connector:delete* はスケジュールを削除します。


```
$ td connector:delete daily_brandwatch_import
```

## Data Extensionsの増分ロード

増分ロードを有効にすることで、ジョブを反復的に実行するようスケジュールできます。次のジョブ実行の反復は、**開始日**と**終了日**の値から計算されます。

次の例では、開始日と終了日の間に11日間の範囲を使用します。


```
Start Date: 2018-03-01T00:00:00Z
End Date: 2018-03-11T00:00:00Z
```

各ジョブは、開始日と終了日の間の期間によって決定される同じ時間範囲を持ちます。メンションの転送は、前回のジョブが完了した時点から開始され、期間が現在の日付を超えるまで続きます。さらなる転送は、完全な期間が利用可能になるまで遅延され、その時点でジョブが実行され、次の期間が利用可能になるまで一時停止します。

例:

- 現在の日付が *2018-04-26* で、*from_date* = *2018-04-01T00:00:00Z* および *to_date* = *2018-04-11T00:00:00Z* で増分ロードを渡す
- Cronは毎日特定の時刻に実行するように設定されている


1回目の実行(2018-04-26): *from_date: 2018-04-01T00:00:00Z to_date: 2018-04-11T00:00:00Z (排他的、メンションは2018-03-10T23:59:59Zまで取得される)*

2回目の実行(2018-04-27): *from_date: 2018-04-11T00:00:00Z to_date: 2018-04-22T00:00:00Z*

3回目の実行(2018-04-28): *to_date* が未来の日付のため実行できません

4回目の実行(2018-04-29): 実行できません

5回目の実行(2018-04-30): 実行できません

6回目の実行(2018-05-01): 実行できません

7回目の実行(2018-05-02): 実行できません

8回目の実行(2018-05-03): *from_date: 2018-04-22T00:00:00Z to_date: 2017-05-03T00:00:00Z*