Google 広告の転送

Google 広告用 BigQuery Data Transfer Service コネクタ（旧称 Google AdWords）を使用すると、Google 広告レポートデータを定期的に読み込むジョブのスケジューリングと管理を自動化できます。

サポートされるレポート

Google 広告用 BigQuery Data Transfer Service は、次の Google Ads API v16 をサポートしています。

Google 広告 v16 レポート

Google 広告レポートが BigQuery Data Transfer Service のテーブルやビューに変換される仕組みについては、Google 広告レポートの変換をご覧ください。

Google 広告レポートが Google 広告管理画面の UI とどのように対応しているかについては、レポートと Google 広告管理画面との対応関係をご覧ください。

レポートオプション	サポート
サポートされている API バージョン	v16
繰り返しの頻度	毎日、データ転送が最初に作成される時刻（デフォルト）時刻を構成できます。
更新ウィンドウ	過去 7 日間（デフォルト）構成可能（最大 30 日）マッチテーブルのスナップショットは 1 日に 1 回取得され、最後の実行日付のパーティションに保存されます。マッチテーブルのスナップショットは、バックフィルや、リフレッシュウィンドウを使用して読み込まれた日には更新されません。
最大バックフィル期間	上限なし Google 広告には、クリックパフォーマンスレポート以外のデータ保持期間の制限はありませんが、BigQuery Data Transfer Service には、1 回のバックフィルでリクエストできる日数に制限があります。バックフィルの詳細については、転送を手動でトリガーするをご覧ください。
MCC アカウントごとのお客様 ID 数	8,000 BigQuery Data Transfer Service は、Google 広告クライアントセンター（MCC）アカウントごとに最大 8,000 個のお客様 ID をサポートしています。

Google 広告の転送からのデータの取り込み

Google 広告から BigQuery にデータを転送すると、データは日付でパーティション分割された BigQuery テーブルに読み込まれます。データが読み込まれるテーブルパーティションは、データソースの日付に対応します。同じ日付の複数の転送をスケジュールすると、BigQuery Data Transfer Service により、対象の日付のパーティションが最新のデータで上書きされます。同じ日に複数回の転送やバックフィルを実行しても、データは重複せず、他の日付のパーティションに対する影響はありません。

更新ウィンドウ

更新ウィンドウとは、データ転送が行われたときにデータ転送でデータが取得される日数です。たとえば、更新ウィンドウが 3 日であり、毎日転送が行われる場合、BigQuery Data Transfer Service は過去 3 日間のソーステーブルからすべてのデータを取得します。この例では、毎日転送が発生すると、BigQuery Data Transfer Service は、当日のソーステーブルのデータのコピーを含む新しい BigQuery 宛先テーブルパーティションを作成し、バックフィル実行を自動的にトリガーして、過去 2 日間のソーステーブルのデータで BigQuery 宛先テーブルパーティションを更新します。自動トリガーされたバックフィル実行は、BigQuery Data Transfer Service コネクタで増分更新がサポートされているかどうかに応じて、BigQuery の宛先テーブルを上書きするか、増分更新します。

データ転送を初めて実行する際に、更新ウィンドウ内で利用可能なすべてのソースデータを取得します。たとえば、更新ウィンドウが 3 日であり、データ転送を初めて実行する場合は、BigQuery Data Transfer Service によって 3 日以内のすべてのソースデータが取得されます。

更新ウィンドウは TransferConfig.data_refresh_window_days API フィールドにマッピングされます。

更新ウィンドウの期間外のデータ（過去のデータなど）を取得する場合や、転送の停止やギャップからデータを復元する場合は、バックフィル実行を開始またはスケジュールできます。

制限事項

Google 広告のデータ転送を構成できる最大頻度は、24 時間に 1 回です。デフォルトでは、転送を作成したときに転送が開始されます。ただし、転送を作成するときに、転送の開始時間を構成できます。
BigQuery Data Transfer Service は、Google 広告の転送中の増分データ転送をサポートしていません。データ転送の日付を指定すると、その日付で使用できるすべてのデータが転送されます。

始める前に

Google 広告のデータ転送を作成する前に、次のことを行います。

BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
Google Merchant Center のデータを保存する BigQuery Data Transfer Service データセットを作成します。
Pub/Sub の転送実行通知を設定する場合は、pubsub.topics.setIamPolicy 権限があることを確認してください。メール通知を設定する場合、Pub/Sub の権限は必要ありません。詳細については、BigQuery Data Transfer Service の実行通知をご覧ください。

必要な権限

データ転送を作成するユーザーに、次の必要な権限が付与されていることを確認します。

BigQuery Data Transfer Service:
- データ転送を作成する bigquery.transfers.update 権限
- bigquery.datasets.get と bigquery.datasets.update の両方（抽出先データセットに対する権限）
bigquery.transfers.update 権限、bigquery.datasets.update 権限、bigquery.datasets.get 権限は、IAM 事前定義ロール bigquery.admin に含まれています。BigQuery Data Transfer Service での IAM ロールの詳細については、アクセス制御のリファレンスをご覧ください。
Google 広告: 転送構成で使用されている Google 広告のお客様 ID または MCC アカウントへの読み取りアクセス権。

Google 広告のデータ転送を作成する

Google 広告レポートのデータ転送を作成するには、Google 広告のお客様 ID または MCC アカウントが必要です。Google 広告のお客様 ID を取得する方法については、お客様 ID の確認をご覧ください。

Google 広告レポートのデータ転送を作成するには、次のいずれかの方法を選択します。

コンソール

Google Cloud コンソールの [データ転送] ページに移動します。

[データ転送] に移動
[転送を作成] をクリックします。
[ソースタイプ] セクションで、[ソース] として [Google Ads] を選択します。
[転送構成名] セクションの [表示名] に、データ転送の名前（例: My Transfer）を入力します。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
[スケジュールオプション] セクションで:
- [繰り返しの頻度] で、データ転送を実行する頻度のオプションを選択します。[日数] を選択した場合は、有効な時刻を UTC で入力します。
  - 時間
  - 日数
  - オンデマンド
- 必要に応じて、[すぐに開始可能] を選択するか、[設定した時刻に開始] を選択して開始日と実行時間を指定します。
[転送先の設定] セクションの [データセット] には、データを保存するために作成したデータセットを選択します。
[データソースの詳細] セクションで、次の操作を行います。
1. [お客様 ID] に Google 広告のお客様 ID を入力します。
2. 省略可: 削除または無効化された項目を除外するオプションと、Google 広告を初めて使用するテーブルを含めるオプションを選択します。
3. 省略可: 含めるテーブルのカンマ区切りのリストを入力します（例: Campaign, AdGroup）。特定のテーブルを除外するには、このリストの先頭に - 文字を配置します（例: -Campaign, AdGroup）。デフォルトでは、すべてのテーブルが含まれています。
4. 省略可: P-MAX レポートに固有のテーブルを含める場合は、このオプションを選択します。P-MAX のサポートの詳細については、P-MAX のサポートをご覧ください。
5. （省略可）[ウィンドウの更新] に 1～30 の値を入力します。
[サービスアカウント] メニューで、Google Cloud プロジェクトに関連付けられたサービスアカウントからサービスアカウントを選択します。ユーザー認証情報を使用する代わりに、サービスアカウントをデータ転送に関連付けることができます。データ転送でサービスアカウントを使用する方法の詳細については、サービスアカウントの使用をご覧ください。
- フェデレーション ID でログインした場合、転送を作成するにはサービスアカウントが必要です。Google アカウントでログインした場合、転送用のサービスアカウントは省略可能です。
- サービスアカウントには必要な権限が付与されている必要があります。
省略可: [通知オプション] セクションで、次の操作を行います。
- 切り替えボタンをクリックしてメール通知を有効にします。このオプションを有効にすると、転送の実行が失敗した場合、転送管理者にメール通知が送信されます。
- 切り替えボタンをクリックして、Pub/Sub 通知を有効にします。[Cloud Pub/Sub トピックを選択してください] でトピック名を選択するか、[トピックを作成] をクリックします。このオプションで、Pub/Sub の転送実行通知を構成します。
[保存] をクリックします。

bq

bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。次のフラグも必要です。

--data_source
--target_dataset
--display_name
--params

次のフラグは省略可能です。

--project_id: 使用するプロジェクトを指定します。このフラグが指定されていない場合は、デフォルトのプロジェクトが使用されます。
--table_filter: データ転送に含めるテーブルを指定します。このフラグが指定されていない場合、すべてのテーブルが含まれます。特定のテーブルのみを含めるには、値のカンマ区切りのリスト（Ad、Campaign、AdGroup など）を使用します。特定のテーブルを除外するには、値の先頭にハイフン（-）を付けます（例: -Ad、Campaign、AdGroup）。
--schedule: クエリの実行頻度を指定します。--schedule を指定しない場合、デフォルトは every 24 hours に設定されます。スケジュールの構文については、schedule の書式をご覧ください。
--refresh_window_days: 転送構成の更新間隔を日数で指定します。デフォルト値は 7 です。
--service_account_name: ユーザーアカウントの代わりに、Google 広告の転送認証に使用するサービスアカウントを指定します。

bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--target_dataset=DATASET \
--display_name=NAME \
--params='PARAMETERS' \
--data_source=DATA_SOURCE \
--table_filter=TABLES \
--schedule=SCHEDULE
--refresh_window_days=REFRESH_DAYS
--service_account_name=SERVICE_ACCOUNT_NAME

ここで

PROJECT_ID はプロジェクト ID です。
DATASET は、データ転送構成のターゲットデータセットです。
NAME は、データ転送構成の表示名です。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
PARAMETERS には、作成される転送構成のパラメータを JSON 形式で指定します。例: --params='{"param":"param_value"}'。Google 広告では、customer_id パラメータを指定する必要があります。オプションで、exclude_removed_items パラメータを true に設定して、削除済みまたは無効化されたエンティティおよび指標が転送されないようにできます。
DATA_SOURCE は、データソース（google_ads）です。
TABLES は、転送に含める、またはデータ転送から除外するテーブルのカンマ区切りリストです。
SCHEDULE は、クエリを実行する頻度です。--schedule が指定されていない場合、デフォルトは転送の作成時から 24 時間ごとです。
REFRESH_DAYS は、転送構成の更新間隔を日数で指定する整数です。デフォルト値は 7 です。
SERVICE_ACCOUNT_NAME は、転送の認証に使用されるサービスアカウント名です。サービスアカウントは、転送の作成に使用した project_id が所有している必要があります。また、必要な権限がすべて付与されている必要があります。

たとえば、次のコマンドは、お客様 ID 123-123-1234 とターゲットデータセット mydataset を使用して、My Transfer という名前の Google 広告のデータ転送を作成します。このデータ転送はデフォルトのプロジェクトで作成されます。

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"customer_id":"123-123-1234","exclude_removed_items":"true"}' \
--data_source=google_ads

コマンドの初回実行時に、次のようなメッセージが表示されます。

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

メッセージの指示に従って、認証コードをコマンドラインに貼り付けます。

API

projects.locations.transferConfigs.create メソッドを使用して、TransferConfig リソースのインスタンスを指定します。

Java

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create ads(formerly AdWords) transfer config
public class CreateAdsTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    // the customer_id only allows digits and hyphen ('-').
    String customerId = "012-345-6789";
    String refreshWindow = "100";
    Map<String, Value> params = new HashMap<>();
    params.put("customer_id", Value.newBuilder().setStringValue(customerId).build());
    params.put("refreshWindow", Value.newBuilder().setStringValue(refreshWindow).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Ads Transfer Config Name")
            .setDataSourceId("adwords")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createAdsTransfer(projectId, transferConfig);
  }

  public static void createAdsTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Ads transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Ads transfer was not created." + ex.toString());
    }
  }
}

Google 広告の転送を手動でトリガーする

Google 広告の転送を手動でトリガーすると、マッチテーブルのスナップショットが 1 日に 1 回取得され、最新の実行日のパーティションに保存されます。手動転送をトリガーしても、次のテーブルのマッチテーブルスナップショットは更新されません。

Ad
AdGroup
AdGroupAudience
AdGroupBidModifier
AdGroupAdLabel
AdGroupCriterion
AdGroupCriterionLabel
AdGroupLabel
AgeRange
Asset
AssetGroup
AssetGroupAsset
AssetGroupListingGroupFilter
AssetGroupSignal
Audience
BidGoal
Budget
Campaign
CampaignAudience
CampaignCriterion
CampaignLabel
Customer
Gender
Keyword
LocationBasedCampaignCriterion
ParentalStatus
Placement
Video

P-MAX のサポート

Google 広告コネクタを使用すると、P-MAX キャンペーンのデータをエクスポートできます。P-MAX のデータはデフォルトではエクスポートされないため、データ転送の作成時に [P-MAX キャンペーンのテーブルを含める] チェックボックスをオンにする必要があります。

P-MAX のデータを含めると、特定のテーブルから ad_group フィールドが削除され、新しいテーブルが含まれます。Google Ads API によって P-MAX のデータがフィルタされるため、ad_group フィールドを含めることはできません。

[P-MAX キャンペーンの表を含める] チェックボックスがオンになっている場合、次の表では ad_group 関連の列は除外されています。

GeoStats
GeoConversionStats
ShoppingProductConversionStats
ShoppingProductStats
LocationsUserLocationsStats

[P-MAX キャンペーンのテーブルを含める] チェックボックスをオンにすると、次のテーブルが追加されます。

Asset
AssetGroup
AssetGroupAsset
AssetGroupListingGroupFilter
AssetGroupSignal
Audience
AssetGroupProductGroupStats
CampaignAssetStats

Google 広告 MCC アカウントのサポート

お客様 ID に固有の複数の Google 広告転送をお持ちのお客様は、クライアントセンター（MCC）アカウントレベルで 1 つの Google 広告転送を設定し、バックフィルをスケジュールして、お客様 ID に固有の個別の Google 広告転送を無効にすることをおすすめします。

Google 広告 MCC アカウントを使用すると、個別のお客様 ID を使用する場合よりもメリットがあります。

複数のお客様 ID を報告するために複数のデータ転送を管理する必要がなくなります。
すべてのお客様 ID が同じテーブルに格納されるため、顧客間のクエリをより簡単に作成できます。
MCC を使用すると、同じ 1 つのジョブで複数のお客様 ID が読み込まれるので、BigQuery Data Transfer Service の読み込み割り当て量の問題が緩和されます。

Google 広告 MCC アカウントの詳細については、管理アカウントの操作と MCC アカウントへのアカウントのリンクについてをご覧ください。

例

次のリストは、特定の Google 広告 MCC アカウントにリンクされているお客様 ID を示しています。

1234567890 - ルート MCC アカウント
- 1234 - サブ MCC アカウント
  - 1111 - お客様 ID
  - 2222 - お客様 ID
  - 3333 - お客様 ID
  - 4444 - お客様 ID
  - 567 - サブ MCC アカウント
    - 5555 - お客様 ID
    - 6666 - お客様 ID
    - 7777 - お客様 ID
- 89 - サブ MCC アカウント
  - 8888 - お客様 ID
  - 9999 - お客様 ID
- 0000 - お客様 ID

MCC アカウントにリンクされたお客様 ID が各レポートに表示されます。BigQuery Data Transfer Service での Google 広告のレポート構造について詳しくは、Google 広告レポートの変換をご覧ください。

お客様 ID 1234567890 の転送構成

ルート MCC アカウント（お客様 ID 1234567890）の転送構成では、次のお客様 ID を含むデータ転送実行が生成されます。

1111（サブ MCC アカウント 1234 を介して）
2222（サブ MCC アカウント 1234 を介して）
3333（サブ MCC アカウント 1234 を介して）
4444（サブ MCC アカウント 1234 を介して）
5555（サブ MCC アカウント 567 およびサブ MCC アカウント 1234 を介して）
6666（サブ MCC アカウント 567 およびサブ MCC アカウント 1234 を介して）
7777（サブ MCC アカウント 567 およびサブ MCC アカウント 1234 を介して）
8888（サブ MCC アカウント 89 を介して）
9999（サブ MCC アカウント 89 を介して）
0000（個別のお客様 ID）

お客様 ID 1234 の転送構成

サブ MCC アカウント 123（お客様 ID 1234）の転送構成では、次のお客様 ID を含むデータ転送実行が生成されます。

1111
2222
3333
4444
5555（サブ MCC アカウント 567 を介して）
6666（サブ MCC アカウント 567 を介して）
7777（サブ MCC アカウント 567 を介して）

お客様 ID 567 の転送構成

サブ MCC アカウント 567（お客様 ID 567）の転送構成では、次のお客様 ID を含むデータ転送実行が生成されます。

5555
6666
7777

お客様 ID 89 の転送構成

サブ MCC アカウント 89（お客様 ID 89）の転送構成では、次のお客様 ID を含むデータ転送実行が生成されます。

8888
9999

お客様 ID 0000 の転送構成

お客様 ID 0000 の転送構成では、個別のお客様 ID のみを含むデータ転送実行が生成されます。

0000

Google 広告データを MCC に移行する

BigQuery Data Transfer Service の既存の Google 広告データを MCC 構造に移行するには、バックフィルを設定して、MCC アカウントにリンクされた転送構成で作成されたテーブルに既存のデータを追加します。バックフィルをスケジュールすると、マッチテーブルは更新されません。

Google 広告の転送設定のトラブルシューティング

データ転送を設定する際に問題が発生した場合は、転送構成のトラブルシューティングにある Google 広告の転送に関する問題をご覧ください。

データに対するクエリを実行する

データが BigQuery Data Transfer Service に転送されると、取り込み時間パーティション分割テーブルにそのデータが書き込まれます。詳細については、パーティション分割テーブルの概要をご覧ください。

自動生成されたビューを使用せずに、テーブルでクエリを直接実行する場合は、そのクエリで _PARTITIONTIME 疑似列を使用する必要があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

Google 広告のサンプルクエリ

次の Google 広告サンプルクエリを使用して転送されたデータを分析できます。このクエリは、Looker Studio などのビジュアリゼーションツールでも使用できます。これらのクエリは、BigQuery Data Transfer Service で Google 広告データのクエリを開始するときに役立つように用意されたものです。これらのレポートで何ができるかに関する質問については、Google 広告の技術担当者にお問い合わせください。

以下の各クエリでは、dataset をデータセット名で置き換えてください。customer_id は、Google 広告のお客様 ID で置き換えます。

キャンペーンの掲載結果

次のサンプルクエリでは、過去 30 日間の Google 広告キャンペーンの掲載結果を分析します。

Console

SELECT
  c.customer_id,
  c.campaign_name,
  c.campaign_status,
  SUM(cs.metrics_impressions) AS Impressions,
  SUM(cs.metrics_interactions) AS Interactions,
  (SUM(cs.metrics_cost_micros) / 1000000) AS Cost
FROM
  `DATASET.ads_Campaign_CUSTOMER_ID` c
LEFT JOIN
  `DATASET.ads_CampaignBasicStats_CUSTOMER_ID` cs
ON
  (c.campaign_id = cs.campaign_id
  AND cs._DATA_DATE BETWEEN
  DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY) AND DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY))
WHERE
  c._DATA_DATE = c._LATEST_DATE
GROUP BY
  1, 2, 3
ORDER BY
  Impressions DESC

bq

  bq query --use_legacy_sql=false '
  SELECT
    c.customer_id,
    c.campaign_name,
    c.campaign_status,
    SUM(cs.metrics_impressions) AS Impressions,
    SUM(cs.metrics_interactions) AS Interactions,
    (SUM(cs.metrics_cost_micros) / 1000000) AS Cost
  FROM
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  LEFT JOIN
    `DATASET.ads_CampaignBasicStats_CUSTOMER_ID` cs
  ON
    (c.campaign_id = cs.campaign_id
    AND cs._DATA_DATE BETWEEN
    DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY) AND DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY))
  WHERE
    c._DATA_DATE = c._LATEST_DATE
  GROUP BY
    1, 2, 3
  ORDER BY
    Impressions DESC'

キーワード数

次のサンプルクエリは、キャンペーン、広告グループ、ステータスごとにキーワードを分析します。このクエリでは、KeywordMatchType 関数を使用しています。キーワードのマッチタイプを使用すると、広告をトリガーする検索語句を制御できます。キーワードのマッチタイプの詳細については、キーワードのマッチタイプについてをご覧ください。

コンソール

  SELECT
    c.campaign_status AS CampaignStatus,
    a.ad_group_status AS AdGroupStatus,
    k.ad_group_criterion_status AS KeywordStatus,
    k.ad_group_criterion_keyword_match_type AS KeywordMatchType,
    COUNT(*) AS count
  FROM
    `DATASET.ads_Keyword_CUSTOMER_ID` k
    JOIN
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  ON
    (k.campaign_id = c.campaign_id AND k._DATA_DATE = c._DATA_DATE)
  JOIN
    `DATASET.ads_AdGroup_CUSTOMER_ID` a
  ON
    (k.ad_group_id = a.ad_group_id AND k._DATA_DATE = a._DATA_DATE)
  WHERE
    k._DATA_DATE = k._LATEST_DATE
  GROUP BY
    1, 2, 3, 4

bq

  bq query --use_legacy_sql=false '
  SELECT
    c.campaign_status AS CampaignStatus,
    a.ad_group_status AS AdGroupStatus,
    k.ad_group_criterion_status AS KeywordStatus,
    k.ad_group_criterion_keyword_match_type AS KeywordMatchType,
    COUNT(*) AS count
  FROM
    `DATASET.ads_Keyword_CUSTOMER_ID` k
  JOIN
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  ON
    (k.campaign_id = c.campaign_id AND k._DATA_DATE = c._DATA_DATE)
  JOIN
    `DATASET.ads_AdGroup_CUSTOMER_ID` a
  ON
    (k.ad_group_id = a.ad_group_id AND k._DATA_DATE = a._DATA_DATE)
  WHERE
    k._DATA_DATE = k._LATEST_DATE
  GROUP BY
    1, 2, 3, 4'