# Meta Dataset Quality インポート連携

Conversions APIを使用してサーバーイベントを共有する広告主は、Meta Events ManagerでEvent Match Qualityスコアを確認できます。ただし、これは個別ベースでのみ機能するため、技術プロバイダーパートナー、代理店パートナー、または広告主が数百から数千のMeta Pixelをビジネスで管理している場合、拡張が困難です。Dataset Quality（旧称Integration Quality）APIは、データセット品質メトリクスをプログラムで大規模に統合することで、この問題の解決に役立ちます。

このコネクタは、Event Match Quality、イベントカバレッジ、イベント重複排除、追加レポート済みコンバージョンを含む、Conversions APIのメトリクスのインポートを支援します。

# 要件と制限

- Treasure Dataに関する基本的な知識があること
- Meta Conversionに関する基本的な知識があること
- Metaアクセストークンとデータセットidを持っていること（詳細はこちらのページを参照してください https://developers.facebook.com/docs/marketing-api/conversions-api/dataset-quality-api）


## 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/)

## ユースケース

例1: データセット別のマッチキーカバレッジ

以下のヒートマップは、複数のデータセットにわたる異なるマッチキー（メール、電話、external_id、fbp、fbcなど）のカバレッジ率（%）を示しています。

- 行: マッチキー（イベントマッチングに使用される識別子）
- 列: データセットID（異なる統合ソースまたはキャンペーンを表す）
- セル: カバレッジパーセンテージ — つまり、特定のマッチキーを含むデータセット内のイベントの割合


![](/assets/output.9c5876adbce9b4892c627fbd8acf5993aa685d831608026d4a80177122015910.5f26d108.png)

このダッシュボードの使用方法:

- 各データセット内の弱いマッチキーを特定する（例: dataset_Bは電話のカバレッジが低い）。
- データセット間で最も大きなギャップがあるマッチキーの改善を優先する。カバレッジが高いほど、Event Match Quality（EMQ）が直接改善されます。
- このビューをEMQトレンドおよび重複排除統計と組み合わせて使用し、データセット品質の全体像を構築します。


# TD ConsoleからMeta Datasetをインポート

## 認証の作成

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

1. **Integrations Hub**を選択します。
2. **Catalog**を選択します。
![](/assets/integrationshub-catalog2.e33c0a4c7d81c40cc83dd056c2143b97b1406220e213cab14ef349d69412ffef.7705d4c2.png)
3. Catalogで連携を検索し、アイコンの上にマウスを置いて**Create Authentication**を選択します。
![](/assets/26617501.d6a5ad453f9fa98b4336af9506dadbd04ea44299e2f9af7fd760f75ac68e3f88.25ec5a77.png)
4. **Credentials**タブが選択されていることを確認し、連携の認証情報を入力します。


### **OAuth認証**

| パラメータ | 説明 |
|  --- | --- |
| Authentication Method | OAuth認証方式 |


![](/assets/screenshot-2025-08-05-at-14.36.31.f70e373307117e54096d66c28e2047c2334dbbf310b3c938f9c3207c7ae89f2b.5f26d108.png)

「Click here to start the OAuth authentication」のリンクをクリックし、Facebookでのログインが成功すると、TD consoleのウェブサイトにリダイレクトされます。その後、Continueボタンをクリックします。

#### **Access Token認証**

![](/assets/screenshot-2025-08-05-at-14.41.04.74927942e3c1d30853178b61180a50593db3ceb2bf4bd74ce2e8e3355d6b2422.5f26d108.png)

| パラメータ | 説明 |
|  --- | --- |
| Authentication | Access Token認証方式 |
| Access Token | MetaアクセストークN |
| App Secret | Metaアプリシークレット |


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/screenshot-2025-08-06-at-15.15.05.aba984cabb5d2dc21cd88832c2b5b0cac89da10bc9a179c886434f39a381fae6.5f26d108.png)

| パラメータ | 説明 |
|  --- | --- |
| Dataset ID | 品質データを取得するデータセット（Pixel）のID。 |
| Agent Name | partner_agentフィールドの正規化された値。partner_agentで送信されたイベントのみをフィルタリングするために使用されます。 |
| Event Type | イベントのタイプ。現在はウェブサイトイベントのみをサポートしています。 |
| Website Metric Type | ウェブサイトのイベントメトリクスで、以下の値をサポートしています  - Event Match Quality - Additional Conversions Reported for Parameters - Event Match Quality Diagnostics - Event Coverage - Additional Conversions Reported for Event Coverage - Event Deduplication - Data Freshness - Additional Conversions Reported for Event - Additional Conversions Reported |


**Next**を選択します。

## データ設定の定義

![](/assets/screenshot-2025-08-06-at-15.16.13.0d48d6df80ba3a5e798f9d708b696415bb6c806b9b326f56ccd3c41f9ffcb65f.5f26d108.png)

| パラメータ | 説明 |
|  --- | --- |
| Retry Limit | 最大リトライ制限。 |
| Initial Retry Wait | 最初のリトライまでの待機時間（秒）。 |
| Maximum Retry Wait | リトライの最大待機時間（秒）。 |
| HTTP Connection Timeout | 接続タイムアウト設定（秒）。 |
| HTTP Read Timeout | 読み取りタイムアウト設定（秒）。 |


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

# WorkflowからMeta Datasetをインポート

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

## ソースの使用

1. ソースを特定します。
2. 一意のIDを取得するには、ソースリストを開き、Meta Dataset Qualityでフィルタリングします。
3. メニューを開き、**Copy Unique ID**を選択します。


![](/assets/26617502.09d9b84b0f1f752c7c95b0bc1c2d8e8b7302e5b91c6a3cb5f01309dadf53a604.25ec5a77.png)

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



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

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


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

1. ymlファイルを特定します。ymlファイルを作成する必要がある場合は、[Amazon S3 Import Integration Using CLI](https://docs.treasuredata.com/display/INT/Amazon+S3+Import+Integration+Using+CLI)を参照してください。
2. td_load>オペレーターを使用してワークフロータスクを定義します。



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

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


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

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | コネクタタイプ | meta_dataset_quality |  | Yes |
| access_token | Metaアクセストークン |  |  | Yes |
| app_secret | Meta OAuth appシークレット。 |  |  | No |
| dataset_id | 品質データを取得するデータセット(Pixel)のID。 |  |  | Yes |
| agent_name | partner_agentフィールドの正規化された値で、partner_agentで送信されたイベントのみをフィルタリングするために使用されます |  |  | No |
| event_type | イベントのタイプ。現在はウェブサイトイベントのみサポートしています。 |  | WEBSITE | Yes |
| web_metric_type | ウェブサイトのイベントメトリックで、以下の値をサポートしています。 | サポートされる値:   - EVENT_MATCH_QUALITY - ADDITIONAL_CONVERSIONS_REPORTED_FOR_PARAMETERS - EVENT_MATCH_QUALITY_DIAGNOSTICS - EVENT_COVERAGE - ADDITIONAL_CONVERSIONS_REPORTED_FOR_EVENT_COVERAGE - EVENT_DEDUPLICATION - DATA_FRESHNESS - ADDITIONAL_CONVERSIONS_REPORTED_FOR_EVENT - ADDITIONAL_CONVERSIONS_REPORTED | EVENT_MATCH_QUALITY | Yes |
| retry_limit | 最大リトライ制限。 |  | 7 | No |
| initial_retry_wait | 最初のリトライまでの待機時間(秒)。 |  | 2秒 | No |
| max_retry_wait | リトライの最大待機時間(秒)。 |  | 240秒 | No |
| connection_timeout | タイムアウト接続設定(秒)。 |  | 300秒 | No |
| read_timeout | 読み取りタイムアウト設定(秒)。 |  | 120秒 | No |


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

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

# CLI (Toolbelt)経由でMetaデータセットからインポート

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

## 設定ファイルの作成(load.yml)


```
in:
```

type: meta_dataset_quality

access_token: token

app_secret: 9111...

dataset_id: 1234567901

agent_name:

event_type: WEBSITE

web_metric_type: EVENT_MATCH_QUALITY

retry_limit: 7

initial_retry_wait: 2

max_retry_wait: 240

connection_timeout: 300

read_timeout: 120


```
out:
  mode: append
```

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

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | コネクタタイプ | meta_dataset_quality |  | Yes |
| access_token | Metaアクセストークン |  |  | Yes |
| app_secret | Meta OAuth appシークレット。 |  |  | No |
| dataset_id | 品質データを取得するデータセット(Pixel)のID。 |  |  | Yes |
| agent_name | partner_agentフィールドの正規化された値で、partner_agentで送信されたイベントのみをフィルタリングするために使用されます |  |  | No |
| event_type | イベントのタイプ。現在はウェブサイトイベントのみサポートしています。 |  | WEBSITE | Yes |
| web_metric_type | ウェブサイトのイベントメトリックで、以下の値をサポートしています。 | サポートされる値:   - EVENT_MATCH_QUALITY - ADDITIONAL_CONVERSIONS_REPORTED_FOR_PARAMETERS - EVENT_MATCH_QUALITY_DIAGNOSTICS - EVENT_COVERAGE - ADDITIONAL_CONVERSIONS_REPORTED_FOR_EVENT_COVERAGE - EVENT_DEDUPLICATION - DATA_FRESHNESS - ADDITIONAL_CONVERSIONS_REPORTED_FOR_EVENT - ADDITIONAL_CONVERSIONS_REPORTED | EVENT_MATCH_QUALITY | Yes |
| retry_limit | 最大リトライ制限。 |  | 7 | No |
| initial_retry_wait | 最初のリトライまでの待機時間(秒)。 |  | 2秒 | No |
| max_retry_wait | リトライの最大待機時間(秒)。 |  | 240秒 | No |
| connection_timeout | タイムアウト接続設定(秒)。 |  | 300秒 | No |
| read_timeout | 読み取りタイムアウト設定(秒)。 |  | 120秒 | No |


## データプレビュー

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


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

guessコマンドは、ソースデータファイルから少なくとも3行2列以上を必要とします。これは、コマンドがソースデータのサンプル行を使用してカラム定義を評価するためです。

システムが予期しないカラム名またはカラムタイプを検出した場合は、load.ymlファイルを変更して再度プレビューしてください。

## ロードジョブの実行

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

Treasure Dataのストレージは時間で分割されているため([データパーティショニング](http://docs.treasuredata.com/display/PD/Data+Partitioning+in+Treasure+Data)を参照)、*--time-column*オプションの指定を推奨します。このオプションが指定されていない場合、データコネクタは最初の*long*または*timestamp*カラムをパーティショニング時間として選択します。*--time-column*で指定するカラムのタイプは、*long*または*timestamp*のいずれかである必要があります。

データに時間カラムがない場合は、*add_time*フィルターオプションを使用して時間カラムを追加できます。詳細については、[add_time Filter Function](http://docs.treasuredata.com/display/PD/add_time+Filter+Function)を参照してください。


```
$ 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*オプションを使用してデータベースとテーブルを自動作成してください。


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

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

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


```
$ 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* コマンドを使用して、新しいスケジュールを作成できます。


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

Treasure Data のストレージは時間によってパーティション分割されているため ([data partitioning](http://docs.treasuredata.com/display/PD/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 などのタイムゾーン略語はサポートされて*おらず*、予期しないスケジュールにつながる可能性があります。

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

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


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

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

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


```
% td connector:show daily_import
```

Name : daily_import

Cron : 10 0 * * *

Timezone : UTC

Delay : 0

Database : joe_db

Table : meta_dataset_quality_shed

Config

in:

access_token: "***"

app_secret: "***"

dataset_id: '1234567890'

event_type: WEBSITE

web_metric_type: EVENT_MATCH_QUALITY

retry_limit: 3

initial_retry_wait: 1

max_retry_wait: 240

connection_timeout: 300

read_timeout: 120

type: meta_dataset_quality

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


```
% td connector:history daily_import
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| JobID  | Status  | Records | Database     | Table           | Priority | Started                   | Duration |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| 578066 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-18 00:10:05 +0000 | 160      |
| 577968 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-17 00:10:07 +0000 | 161      |
| 577914 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-16 00:10:03 +0000 | 152      |
| 577872 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-15 00:10:04 +0000 | 163      |
| 577810 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-14 00:10:04 +0000 | 164      |
| 577766 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-13 00:10:04 +0000 | 155      |
| 577710 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-12 00:10:05 +0000 | 156      |
| 577610 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-11 00:10:04 +0000 | 157      |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
8 rows in set
```

### スケジュールの削除

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


```
$ td connector:delete daily_import
```