Meta Dataset Quality インポート連携

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

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/

ユースケース

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

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

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

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

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

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

認証の作成

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

1. Integrations Hubを選択します。

2. Catalogを選択します。

   

3. Catalogで連携を検索し、アイコンの上にマウスを置いてCreate Authenticationを選択します。

   

4. Credentialsタブが選択されていることを確認し、連携の認証情報を入力します。

OAuth認証

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

Access Token認証

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

ソースの作成

1. TD Consoleを開きます。

2. Integrations Hub > Authenticationsに移動します。

3. 新しい認証を見つけて、New Sourceを選択します。

接続の作成

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

2. Nextを選択します。

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

ソーステーブルの特定

Nextを選択します。

データ設定の定義

Nextを選択します。

Data Preview

インポートを実行する前に、Generate Preview を選択してデータのプレビューを表示できます。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を選択します。

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

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

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

ymlファイルを使用する

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

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

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

パラメータリファレンス

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

サンプルワークフローコードについては、Treasure Boxesを参照してください。

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

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

設定ファイルの作成(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

パラメータリファレンス

データプレビュー

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

$ td connector:preview load.yml​

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

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

ロードジョブの実行

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

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

データに時間カラムがない場合は、add_timeフィルターオプションを使用して時間カラムを追加できます。詳細については、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 の既存テーブルにデータを追加したり、データを置き換えたりすることができます。

実行のスケジューリング

増分ファイルインポートのために、定期的なデータコネクター実行をスケジュールできます。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 も参照)、--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