AdInsights
広告レポートをクエリします。広告レポート情報へのアクセスには、ads_read アクセス許可が必要です。
テーブル固有の情報
Facebook AdInsights ではレポートから取得できる情報と同等のものが要求できます。
Select
AdInsights を要求する場合は、Target を含める必要があります。Target は、インサイトを取得するエレメントを指定します。 対象Target は、AdAccount、Campaign、AdSet、またはAd です。次に例を示します。SELECT * FROM AdInsights WHERE Target = 'act_123456'
Adinsights に対するSELECT * クエリでデフォルトで常にフェッチされるカラム：
- Target
- DateStart
- DateEnd
- AccountCurrency
- AdAccountId
- AdAccountName
- Impressions
- Spend
指標カラム
Adinsights レポートでSELECT * クエリを実行する場合、すべての指標カラムがFacebook から取得されるわけではありません。これは、カラムメタデータが過去のリクエストで取得された場合、特定のカラムが "0" またはNULL 値を返す可能性があることを意味します。このデータをフェッチするには、SELECT * を使用するのではなく、クエリのSELECT 部分にこれらのカラムを含める必要があります。Adinsights でこの挙動を示す可能性のある指標カラムは、以下のとおりです。
- BuyingType
- Clicks
- ConversionRateRanking
- CostPerEstimatedAdRecallers
- CostPerInlineLinkClick
- CostPerInlinePostEngagement
- CostPerUniqueClick
- CostPerUniqueInlineLinkClick
- CPC
- CPM
- CPP
- CTR
- EstimatedAdRecallRate
- EstimatedAdRecallers
- Frequency
- Impressions
- InlineLinkClicks
- InlineLinkClicksCounter
- InlinePostEngagement
- InstantExperienceClicksToOpen
- InstantExperienceClicksToStart
- InstantExperienceOutboundClicks
- Objective
- QualityRanking
- Reach
- Spend
- UniqueClicks
- UniqueCTR
- UniqueInLineLinkClicks
- UniqueInLineLinkClickCounter
- UniqueLinkClicksCounter
- Checkins
- EventResponses
- LinkClicks
- OfferSaves
- OutboundClicks
- PageEngagements
- PageLikes
- PageMentions
- PagePhotoViews
- PostComments
- PostEngagements
- PostShares
- PostReactions
- PageTabViews
- Video3SecondViews
Date Preset
データ範囲を指定するには、DateStart とDateEnd、またはDatePreset のいずれかを使用します。 DatePreset で使用できる値は次のとおりです。- maximum
- today
- yesterday
- this_week_sun_today
- this_week_mon_today
- last_week_sun_sat
- last_week_mon_sun
- last_3d
- last_7d
- last_14d
- last_28d
- last_30d
- last_90d
- this_month
- last_month
次に例を示します。
SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DateStart >= '01/01/2015' AND DateEnd <= '03/31/2015'
SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DatePreset = 'last_90d'
各レポート行に何日を含めるかを指定するには、TimeIncrement を使用します。次に例を示します。
SELECT DateStart, DateEnd, AdAccountId, Age, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DatePreset = 'last_90d' AND TimeIncrement = '7'
SELECT DateStart, DateEnd, AdAccountId, Age, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND DatePreset = 'last_90d' AND TimeIncrement = 'monthly'
インサイトを取得するレベルを指定するには、Level カラムを使用します。有効な値は、ad、adset、campaign、account です。次に例を示します。
SELECT DateStart, DateEnd, AdAccountId, Age, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' AND Level = 'campaign'
Note： DatePreset およびブレークダウンはFacebook によって頻繁に変更されることがあります。Facebook 側の変更により、上のリストは古くなっている可能性があります。最新のブレークダウンおよび、date presets を参照するには、https://developers.facebook.com/docs/marketing-api/insights/ でFacebook のドキュメントのパラメータとブレークダウンを参照してください。
ブレークダウンカラム
ブレークダウンカラムが多く存在します。一般的には、一度に1つのブレークダウンカラムしか選択できません。SELECT * を使うと、ブレークダウンカラムは使われません。利用可能なブレークダウンカラムは次のとおりです。
- Age：Gender と一緒に選択することができます。
- Country
- FrequencyValue
- Gender：Age と一緒に選択することができます。
- HStatsByAdvertiserTZ (Hourly Stats by Advertizer Timezone)
- HStatsByAudienceTZ (Hourly Stats by Audience Timezone)
- ImpressionDevice：PublisherPlatform、またはPublisherPlatform とPlatformPosition の両方と一緒に選択することができます。
- PlatformPosition：PublisherPlatform と一緒に選択される必要があります。ImpressionDevice と一緒に選択することもできます。
- PublisherPlatform：PlatformPosition、ImpressionDevice、またはPlatformPosition とImpressionDevice 両方と一緒に選択できます。
- ProductId
- Region
他の多くのカラムは、標準SQL WHERE clause modifiers と使うことができます。次に例を示します。
SELECT DateStart, DateEnd, AdAccountId, Spend, Impressions FROM AdInsights WHERE Target = 'act_123456' WHERE Impressions > 10000 AND Spend < 1000
Facebook Ads では、同時に選択できるブレークダウンに制限を課しているため、デフォルトでは、connector に指定されるクエリのブレークダウンにも同様の制限を課しています。必要に応じて、IgnoreValidationException をTrue に設定することで、ブレークダウン制限事項の内部施行をバイパスすることができます。この場合、指定されたすべてのブレークダウンの組み合わせがそのままFacebook に渡されます。
Note： DatePreset およびブレークダウンはFacebook によって頻繁に変更されることがあります。Facebook 側の変更により、上のリストは古くなっている可能性があります。最新のブレークダウンおよび、date presets を参照するには、https://developers.facebook.com/docs/marketing-api/insights/ でFacebook のドキュメントのパラメータとブレークダウンを参照してください。
クエリサイズの管理
Sometimes if a query is too large for Facebook to process on its end, you might receive this error: Please reduce the amount of data you're asking for, then retry your request. The error appears to be triggered by individually dense fields, and not the page size.
If the connector encounters this error when first executing certain types of queries, the driver attempts to retry the query at the next lowest level of ad object, down to the level defined in RetryLevel, as long as the query does not include the Level parameter. (If the Level parameter is specified in a query, the driver does not attempt to retry beyond the ad object level specified by Level. For further information, see RetryLevel.) Note that since spreading queries across more granular ad objects increases the number of requests executed for the query, it can decrease query performance.
If you continue to receive this error, try either reducing the date range of the query, or removing expensive columns.
A good method for finding and removing expensive columns is to use a binary search by removing half of the columns you are selecting and retrying the query. If you get the same error, reduce the remaining columns by half and try again. If you do not get an error, add back half of the columns you just removed, and try again.
Columns
| Name | Type | Description |
| Target | String | インサイトを取得するアカウント、キャンペーン、広告グループ、広告のID。 |
| DatePreset | String | DateStart およびDateEnd を指定する代替手段。日付の範囲は前もって指定された値に基づき自動的に計算されます。
使用できる値は次のとおりです。maximum, today, yesterday, this_week_sun_today, this_week_mon_today, last_week_sun_sat, last_week_mon_sun, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month |
| DateStart | Date | インサイトの取得開始日。これは、Facebook UI のReport Start フィールドです。これは、Facebook UI のReport Start フィールドです。 |
| DateEnd | Date | インサイトの取得終了日。これは、Facebook UI のReport End フィールドです。これは、Facebook UI のReport End フィールドです。 |
| TimeIncrement | String | データの集計日数。整数（1-90）、月一回、または毎日（all_days）。この値は範囲またはプリセット日を、より小さなインクリメントに分割します。
デフォルト値は1です。 |
| Level | String | 結果を表示するレベル。
使用できる値は次のとおりです。ad, adset, campaign, account |
| AccountCurrency | String | 広告アカウントで使用されている通貨。 |
| ActionAttributionWindows | String | アクションのアトリビューションウィンドウが何であるかを決定するカンマ区切りのリスト。例えば、28d_click は、API が誰かが広告をクリックしてから28日後に起こったアクションのすべてを返します。デフォルトオプションは、[1d_view,28d_click] を意味します。使用できる値は、1d_view、7d_view、28d_view、1d_click、7d_click、28d_click、default です。 |
| AdAccountId | String | レポート行と関連のある広告アカウントのID。 |
| AdAccountName | String | レポート行と関連のある広告アカウントの名前。 |
| CampaignId | String | レポート行と関連のあるキャンペーンのID。 |
| CampaignName | String | レポート行と関連のあるキャンペーンの名前。 |
| AdSetId | String | レポート行と関連のある広告セットのID。 |
| AdSetName | String | レポート行と関連のある広告セットの名前。 |
| AdId | String | レポート行と関連のある広告のID。 |
| AdName | String | レポート行と関連のある広告の名前。 |
| BuyingType | String | ターゲット広告がキャンペーンで支払われる方法。 |
| Clicks | Long | 広告がクリックされた合計回数。これには、何を宣伝しているかによってページのいいね！、イベント応答、アプリのインストールを含めることができます。これは、Facebook UI のClicks (All) フィールドです。 |
| ConversionRateRanking | String | コンバージョン率ランキング。 |
| CostPerEstimatedAdRecallers | Decimal | 2日以内に要求された場合にあなたの広告を思い出す人一人の想定コストの平均。 |
| CostPerInlineLinkClick | Decimal | 広告内のリンクのクリックあたりの平均コスト。 |
| CostPerInlinePostEngagement | Decimal | 投稿のエンゲージメントあたりの平均コスト。 |
| CostPerUniqueClick | Decimal | 複数広告のユニーククリックあたりの平均コスト。かかった費用をユニーククリック数で割って計算します。 |
| CostPerUniqueInlineLinkClick | Decimal | インラインリンクのユニーククリックごとに支払った平均コスト。 |
| CPC | Decimal | 複数広告のクリックあたりの平均コスト。かかった費用をクリック数で割って計算します。 |
| CPM | Decimal | 広告で1,000インプレッションを獲得するために支払った平均コスト。 |
| CPP | Decimal | 広告をユニークユーザー1,000人に表示するために支払った平均コスト。 |
| CTR | Double | クリックされた回数をインプレッション数で割ったもの。これは、Facebook UI のCTR (All) % フィールドです。 |
| EstimatedAdRecallRate | Double | 広告をrecall したユーザーの推定人数を、広告を表示した人数で割ったもの。 |
| EstimatedAdRecallers | Double | 2日以内に要求された場合にあなたの広告を思い出すと想定される人の数。 |
| Frequency | Double | 広告が一人に対して表示された平均回数。 |
| Impressions | Long | 広告が表示された回数。モバイルアプリでは、広告が初めて表示されたときにカウントします。その他のFacebook インターフェースでは、広告が初めてニュースフィードに表示されたとき、または右カラムに表示されるたびにカウントします。 |
| InlineLinkClicks | Long | 広告内のリンクがクリックされた合計回数。 |
| InlineLinkClicksCounter | Double | リンクへのインラインクリックのクリックスルー率。 |
| InlinePostEngagement | Long | 投稿のエンゲージメントの総数。 |
| InstantExperienceClicksToOpen | Long | instant_experience_clicks_to_open |
| InstantExperienceClicksToStart | Long | instant_experience_clicks_to_start |
| InstantExperienceOutboundClicks | Long | instant_experience_outbound_clicks |
| Objective | String | キャンペーンに設定した目標。広告で達成したいことを目的は反映します。 |
| QualityRanking | String | 品質ランキング。 |
| Reach | Long | 広告が表示された人数。 |
| Spend | Decimal | これまでに使った費用の合計。 |
| UniqueClicks | Long | 広告をクリックしたユニークユーザーの合計人数。例えば、3人が同じ広告を5回見たら、ユニーククリックは3となります。 |
| UniqueCTR | Double | 広告をクリックした人数を、広告を表示した人数で割ったもの。例えば、ユニーククリック数が20で広告が1,000ユニークユーザーに表示された場合、ユニーククリックスルー率は2% となります。 |
| UniqueInlineLinkClicks | Long | 広告のユニークインラインリンククリック数。これは、Facebook UI のUnique Clicks to Link フィールドです。 |
| UniqueInlineLinkClickCounter | Double | リンクへのユニークインラインクリックのクリックスルー率。 |
| UniqueLinkClicksCounter | Double | リンクへのクリックのユニーククリックスルー率。広告のリンクをクリックしてFacebook から離れた人数を、広告を表示した人数で割ったものです。例えば、リンクへのユニーククリック数が20で広告が1,000ユニークユーザーに表示された場合、ユニーククリックスルー率は2% となります。 |
| Checkins | Int | 広告に起因するチェックイン数。 |
| EventResponses | Int | 広告に起因するイベントレスポンス数。 |
| LinkClicks | Int | 広告に起因するリンクのクリック数。 |
| OfferSaves | Int | 広告に起因する受信オファー数。 |
| OutboundClicks | Int | 広告に起因するアウトバウンドクリック数。 |
| PageEngagements | Int | 広告に起因するページのエンゲージメント数。 |
| PageLikes | Int | 広告に起因するページのいいね数。 |
| PageMentions | Int | 広告に起因するページのメンション数。 |
| PagePhotoViews | Int | 広告に起因する写真ビュー数。 |
| PostComments | Int | 広告に起因する投稿のコメント数。 |
| PostEngagements | Int | 広告に起因する投稿のエンゲージメント数。 |
| PostShares | Int | 広告に起因する投稿のシェア数。 |
| PostReactions | Int | 広告に起因する投稿のリアクション数。 |
| PageTabViews | Int | 広告に起因するタブビュー数。 |
| Video3SecondViews | Int | 広告に起因する動画のビュー数。少なくとも3秒、または動画が3秒未満の場合は動画全体が再生された場合に、再生回数がカウントされます。 |
| PixelAddToCart | Int | Pixel adds to cart. |
| PixelPurchase | Int | Pixel purchases. |
| Age | String | この行の指標の年齢範囲。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| Country | String | この行の指標の国。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| DevicePlatform | String | 広告の表示に使うデバイスまたはプラットフォーム。このブレークダウンカラムは他のブレイクダウンカラムとは同時に選択できない場合があります。 |
| DMA | String | 指定されたマーケティング範囲。このブレークダウンカラムは他のブレイクダウンカラムとは同時に選択できない場合があります。 |
| FrequencyValue | String | リーチ＆フリークエンシーキャンペーンの広告が一人に表示された回数。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| Gender | String | この行の指標の性別。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| HStatsByAdvertiserTZ | String | 広告主にスタッツが記録される期間。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| HStatsByAudienceTZ | String | オーディエンスにスタッツが記録される期間。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| ImpressionDevice | String | 広告の表示に使うデバイス。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| PlacePageId | String | 対応する場合に使われる場所ページ。このブレークダウンカラムは他のブレイクダウンカラムとは同時に選択できない場合があります。 |
| PlatformPosition | String | プラットフォーム上の位置。 |
| ProductId | String | 広告で宣伝されているプロダクトID。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| PublisherPlatform | String | 広告が掲載されたプラットフォーム。 |
| Region | String | 広告が表示された地域。これはブレークダウンカラムです。このカラムを選択すると指標によって結果がさらにブレークダウンされます。 |
| AdEffectiveStatus | String | 広告アカウントより低いレベルでインサイトを取得する際にサポートされているステータスの入力専用リスト。有効な値の例については、AdStatus にリストされている値を参照してください。 |
| UseAsync | Boolean | インサイトの取得に非同期呼び出しを使用する必要があるかどうかを示すboolean。 |
| DefaultSummary | Boolean | デフォルトサマリーを取得するかどうかを示すboolean。 |