Facebook Ads Insights のデータコネクタ(旧称 Facebook Ads Reporting)は、Facebook 広告キャンペーンの結果データをインポートすることができます。
- Treasure Data の基本知識
- Facebook Marketing API、特に Ads Insights API の基本知識
- 管理者権限として Admin または Advertiser が必要
Treasure Data Connections に移動し、Facebook Ads を検索して選択します。次のダイアログが開きます。
2つの認証方法をサポートしています:
- OAuth
- Access Token
Facebook の既存の OAuth 接続を選択するか、OAuth connection の下にあるリンクを選択して新しい接続を作成します。
- 新しい OAuth 接続を作成する
ポップアップウィンドウで Facebook アカウントにログインします:
そして、Treasure Data アプリへのアクセスを許可します。
Treasure Data Connections にリダイレクトされます。最初のステップ(新しい接続を作成する)を繰り返し、新しい OAuth 接続を選択します。
Access Token を作成するには、セクション3の「Facebook Token の取得」を参照してください。
接続を作成すると、自動的に Authentications タブに移動します。作成した接続を探して、New Source を選択します。
次のダイアログが開きます。
以下の詳細を編集します:
- Ad Account ID
- Data Level
- Import Metadata for Related Objects
- Import all Insights or Insights Fields
- Breakdowns
- Filtering
- Action Attribution Windows
- Start and End Date or Incremental
- Reporting Period
これらのパラメータの詳細は次のとおりです:
Ad Account ID を追加します。これはこちらの説明に従って見つけることができます。
Ads オブジェクトレベルです。使用可能なオプションは、Campaign、Ad Set、および Ad です。
デフォルトでは、Import metadata for related objects はチェックされておらず、コネクタは基本的なメタデータフィールドのみをインポートします: created_time、effective_status、status。
これをチェックすることで、インポートする関連オブジェクトまたは個別のメタデータフィールドを指定できます。
すべての関連 edges をインポートするには、All Metadata Fields を選択します。Fetch Metadata に各 edge を追加することで、インポートする edges を選択できます。
Ads オブジェクトに関連付けられたメタデータフィールドです。Individual Metadata Fields を選択すると、必要なフィールドのみをインポートできます。Metadata Fields の下でフィールドを選択します。
edge{field1, field2…} を使用して、Ads オブジェクトの edges にアクセスすることもできます。
Insight フィールドは、キャンペーンのパフォーマンスに関するデータを提供します。
デフォルトでは、Import all insights fields がチェックされています。
Import all insights fields のチェックを外して、特定のフィールドを選択できます。
Insights フィールドの date_start と date_stop は、明示的に設定されていない場合、デフォルトで追加されます。Insight の値は、Ads オブジェクトの状態によって空の場合があります。フィールドに値が含まれていない場合でも、エラーは生成されません。
Breakdowns は、異なるセットまたはコホートにグループ化された Ads Insights レスポンスをキャプチャするために使用されます。サポートされている breakdowns は次のとおりです:
age
gender
country
region
hourly_stats_aggregated_by_advertiser_time_zone
報告されたInsightsデータのフィルター。フォーマット: フィールド —> オペレーター —> 値、action_typeはカンマ区切りの値でINオペレーターをサポートします。例: post_like, like
アクションのアトリビューションウィンドウを決定します。サポートされる値は以下の通りです:
- 1d_view
- 7d_view
- 28d_view
- 1d_click
- 7d_click
- 28d_click
明示的に設定されていない場合、デフォルト値は: (["1d_view","28d_click"]) です。
IncrementalインポートとStart Dateを指定するかどうかを選択します。
incrementalを有効にすることで、各増分ロードの期間(日数)を定義できます。デフォルトは1日です。Start Dateが指定されていない場合、デフォルトは過去30日間に設定されます。
取得されるデータには、前日の深夜まで利用可能なデータが含まれます。
Start DateとEnd Dateを使用してレポート期間を選択した後、期間全体の結果を取得するか、より小さな時間単位で結果を取得するかを選択できます。All Daysを選択すると、期間全体で1つの結果セットが取得されます。monthlyを指定すると、指定された期間内の各暦月ごとに1つの結果セットが取得されます。
または、In Daysを選択して指定したN日間の期間ごとに1つの結果セットを取得することもできます。1から90までの日数を指定できます。
パラメーターの指定が完了したら、Nextを選択します。以下のダイアログと同様のデータのプレビューが表示されます。Nextを選択します。プレビューを超えて進めない場合は、Preview while Importing Dataを参照してください。
以下のダイアログに示すように、データを転送するデータベースとテーブルを選択します:
以下のダイアログを使用してデータ転送のスケジュールを指定し、Start Transferを選択します。
新しいデータ転送が進行中としてMy Input Transfersタブの下に表示され、対応するジョブがJobsセクションに表示されます。
これで、データの分析を開始する準備が整いました!
最新のTD Toolbeltをインストールします。
Facebookは3種類のトークンを提供しています。期限切れのないPage Access Tokenの使用を推奨します。User Tokenも使用できますが、延長しても2か月後に期限切れになります。バッチ処理には適していません。
期限切れのないPage Access Tokenの取得方法については、Facebook Long-Lived Access Tokensを参照してください。
facebook_ads_reportingコネクターに対してtd connector:guessを実行する必要はありません。
以下のようにconfig.ymlを準備します:
in:
type: "facebook_ads_reporting"
ad_account_id: '[your ad account id]'
access_token: "[your Facebook access token]"
data_level: ad
fields:
- clicks
- impressions
metadata_import: all
metadata_edge:
- adrules_governed
- copies
- keywordstats
- leads
- targetingsentencelines
filtering:
- {field : "clicks", operator: "GREATER_THAN", value: 10}
- {field : "impressions", operator: "GREATER_THAN", value: 200}
out:
mode: appendpreviewコマンドを使用してデータのプレビューを表示できます。
td connector:preview config.yml利用可能なモードの詳細については、以下の表を参照してください。
| Option name | Description | Type | Required? | Default value |
|---|---|---|---|---|
| ad_account_id | access_tokenのアドアカウントID | string | yes | — |
| access_token | Access Token。期限切れのないトークンの使用を推奨します(次のセクションを参照) | string | yes | — |
| app_secret | 設定されている場合、appsecret_proofパラメーターがAPIへのアクセスに使用されます | string | optional | — |
| metadata_import | 関連エッジまたは個別のメタデータフィールドをインポートしますか? 利用可能なオプションはallとindividualです | string | optional | individual |
| metadata_edge | インポートする関連エッジ。metadata_importがallの場合のみ有効です。関連エッジを参照してください。 | array | optional | — |
| metadata_fields | 指定されたオブジェクトに対して取得したいメタデータフィールド。利用可能なフィールドを確認してください。 | array | optional | created_time, status, effective_status |
| fields | Insightsに対して取得したいフィールド。利用可能なフィールドを確認してください。 | array | optional | — |
| breakdowns | 詳細についてはbreakdownsを参照してください。 | string | optional | — |
| filtering | 詳細についてはfilterを参照してください。 | array | optional | — |
| action_attribution_windows | アクションのアトリビューションウィンドウを決定します。たとえば、28d_clickは広告がクリックされてから28日以内に発生したすべてのアクションをAPIが返すことを意味します。 | array | optional | — |
| retry_limit | 最大リトライ回数 | integer | optional | 5 |
| retry_initial_wait_sec | エクスポネンシャルバックオフの初期値の待機秒数 | integer | optional | 10 |
| last_fetched_at | この日付以降のデータのみをインポートします。指定されていない場合は、今日から30日前（つまり、today - 30 days）になります。推奨形式: %m/%d/%Y または %Y-%m-%dT%H:%M:%S.%L%Z | string | optional | — |
| incremental | embulk run -c config.diffで "config_diff" を生成する場合はtrue | bool | optional | true |
| duration | 開始日からインサイトデータを取得する日数。詳細は付録Bを参照してください。 | integer | optional | 1 |
| time_increment | 整数の場合、1から90までの日数を指定します。last_fetched_atとlast_fetched_untilを使用してレポート期間を選択した後、期間全体の結果を取得するか、より小さな時間スライスの結果を取得するかを選択できます。"all_days"を使用すると、期間全体の1つの結果セットが得られます。"monthly"を使用すると、指定された期間内の各カレンダー月ごとに1つの結果セットが得られます。または、このパラメータで指定されたN日間ごとに1つの結果セットを取得できます。詳細は付録Bを参照してください。 | string | optional | 1 |
| last_fetched_until | この日付までのデータのみをインポートします。指定されていない場合は今日になります。推奨形式: last_fetched_atを参照してください。詳細は付録Cを参照してください。 | string | optional | — |
| add_time_column | trueの場合、インサイトのdate_stop値に基づいて"time"カラムが自動的に追加されます。それ以外の場合は、upload_timeによって"time"カラムが追加されます | bool | optional | true |
| data_level | データレベルを取得します。Facebookインサイトレベル: Campaign –> Adset –> Ad。使用可能なオプションは "campaign"、"adset"、"ad"、または "ad_creative" です。 | string | optional | "ad" |
| api_version | 使用するFacebook APIのバージョン。デフォルトはv3.2です。指定されたバージョンがv3.1より古い場合（非推奨）、プラグインは "v3.2" を使用します | string | optional | "v3.2" |
| limit_per_page | ページあたりのレコード数。"Please reduce the amount of data you're asking for, then retry your request"というエラーメッセージが表示された場合は、この値を減らしてください | integer | optional | 100000 |
- ad_studies
- adrules_governed
- ads
- adsets
- copies
- activities
- ad_studies
- adrules_governed
- ads
- copies
- targetingsentencelines
- adrules_governed
- copies
- keywordstats
- leads
- targetingsentencelines
- durationはincremental = trueの場合にのみ有効です
- durationはlast_fetched_atに基づいてリクエストの時間範囲を計算するために使用されます。たとえば、last_fetched_at = 02/01/2017でduration = 2の場合、リクエストする時間範囲は02/01/2017 → 02/02/2017になります
Facebookリクエストパラメータに直接変換すると:
.time_range({"since":"2017-02-01","until":"2017-02-02"})- このパラメータを使用する場合、ブレークダウンの動作はありません。時間範囲全体のインサイト値を返します。
- 注: last_fetched_atが指定されていない場合、今日から30日前（つまり、today – 30 days）になります
- time_incrementは、インサイトデータを日数で分割したい場合に使用します。結果は、インクリメンタルモードとdurationを使用しない場合に最も認識しやすくなります。
例:
incremental: false
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017
time_increment: 1上記の設定を使用すると、2017年3月全体を1回の実行でインポートでき、それでも日次で分割できます。
- durationはincrementalモードで使用されます
- time_incrementは公式のFacebookパラメータです
- 重要な注意事項: durationとtime_incrementの両方が使用可能な場合（デフォルト）、durationの値がtime_incrementより小さい場合、durationはtime_incrementよりも優先されます。つまり、duration = 1の場合、2日ごとのブレークダウンデータ（time_increment = 2）は取得できず、結果は1日分のデータになります。一方で、2日間のduration（duration = 2）に対して日次でデータを分割（time_increment = 1）することは完全に可能です。
- last_fetched_untilはオプションであり、その唯一の用途はインポートするデータを終了日で制限することです。
例: 2017年3月のデータをインポートするジョブがあり、毎日データを取得するために繰り返し実行するようにスケジュールされています。したがって、次の設定を使用してこれを実現できます:
incremental: true
duration: 1
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017注: ご覧のとおり、durationを使用してジョブを繰り返し実行することでtime_incrementの効果をシミュレートできますが、より多くのリクエストが発生します（リクエストレート制限により早く到達します）。
- スケジュールされたジョブが（最終的に）設定されたlast_fetched_untilを超えた場合、空の結果が返されます。
Facebook APIの最近の変更により、Data Connectorが更新されました。
変更前: 一部のフィールドが追加されましたが、値が空だったため、出力スキーマに一部のカラムが欠落していました。
変更後: 一部の新しいカラムが追加されますが、値が含まれていない場合があります。出力スキーマは、入力設定と必須フィールドから組み合わされます。
必須フィールドと暗黙的に追加されるカラムは次のとおりです:
メタデータフィールド
- created_time
- effective_status
- status
インサイトフィールド
- date_start
- date_stop
以前の更新でスキップされた可能性のある無効な**fields**は、更新後にエラーになります。インサイトフィールドとメタデータフィールドの完全なリファレンスについては、次のリンクのFieldsセクションを参照してください: