[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-18。"],[[["\u003cp\u003eThis document outlines how to integrate Google Ads data into the Cortex Framework Data Foundation for comprehensive marketing analysis.\u003c/p\u003e\n"],["\u003cp\u003eThe integration process involves configuring settings in the \u003ccode\u003econfig.json\u003c/code\u003e file, including parameters for deploying Google Ads, enabling Change Data Capture (CDC), and setting the data lookback period.\u003c/p\u003e\n"],["\u003cp\u003eCortex Framework leverages the Google Ads API to retrieve data, with current templates utilizing version 17.1, and requires specific authentication and credentials setup within Google Cloud and Secret Manager.\u003c/p\u003e\n"],["\u003cp\u003eData ingestion from Google Ads to the Cortex Framework is managed through Airflow DAGs, using Dataflow pipelines controlled by settings in the \u003ccode\u003eingestion_settings.yaml\u003c/code\u003e file for source-to-raw and raw-to-CDC data flows.\u003c/p\u003e\n"],["\u003cp\u003eThe reporting layer of Google Ads data in Cortex Framework can be customized through the \u003ccode\u003ereporting_settings.yaml\u003c/code\u003e file, allowing for tailored generation of BigQuery objects.\u003c/p\u003e\n"]]],[],null,["# Integration with Google Ads\n===========================\n\nThis page describes the required configurations to bring data from Google Ads\nas a data source of the marketing workload of Cortex Framework Data Foundation.\n\n[Google Ads](https://ads.google.com/) is an online advertising\nplatform that allows businesses to advertise their products or services\nacross various Google properties. Cortex Framework brings your\nGoogle Ads data together with other marketing channels, analyzes\nit comprehensively, and uses AI to improve your campaign results.\n\nThe following diagram describes how Google Ads data is\navailable through the marketing workload of Cortex Framework Data Foundation:\n\n**Figure 1**. Google Ads data source. **Note:** For accessing configuration files, analytical views and models for the Google Ads data source, see the [data source directory](https://github.com/GoogleCloudPlatform/cortex-data-foundation/tree/main/src/marketing/src/GoogleAds).\n\nConfiguration file\n------------------\n\nThe [`config.json`](https://github.com/GoogleCloudPlatform/cortex-data-foundation/blob/main/config/config.json) file configures the settings required to transfer data from\nany data source, including Google Ads. This file contains the following parameters for\nGoogle Ads: \n\n \"marketing\": {\n \"deployGoogleAds\": true,\n \"GoogleAds\": {\n \"deployCDC\": true,\n \"lookbackDays\": 180,\n \"datasets\": {\n \"cdc\": \"\",\n \"raw\": \"\",\n \"reporting\": \"REPORTING_GoogleAds\"\n }\n }\n }\n\nThe following table describes the value for each Google Ads marketing parameter:\n\nData Model\n----------\n\nThis section describes the Google Ads Data Model using the Entity\nRelationship Diagram (ERD).\n\n[](/static/cortex/docs/images/erd_gads.png)\n**Figure 2**. Google Ads: Entity Relationship Diagram.\n\n### Base views\n\nThese are the blue objects in the ERD and are views on CDC tables with\nno transforms other than some column name aliases. See scripts in\n[`src/marketing/src/GoogleAds/src/reporting/ddls`](https://github.com/GoogleCloudPlatform/cortex-data-foundation/tree/main/src/marketing/src/GoogleAds/src/reporting/ddls).\n\n### Reporting views\n\nThese are the green objects in the ERD and are reporting views that contain\naggregate metrics. See scripts in\n[`src/marketing/src/GoogleAds/src/reporting/ddls`](https://github.com/GoogleCloudPlatform/cortex-data-foundation/tree/main/src/marketing/src/GoogleAds/src/reporting/ddls).\n\nAPI connection\n--------------\n\nCortex Framework ingestion templates use the\n[Google Ads API](https://developers.google.com/google-ads/api/docs/start)\nto retrieve reporting attributes and metrics from Google Ads.\nThe current Cortex Framework templates use Google Ads API\n[version 17.1](https://developers.google.com/google-ads/api/fields/v17/overview).\nConsider the Google Ads API limitations:\n\n- **Basic access operations per day** : 15000 (paginated requests containing valid `next_page_token` are not counted).\n- **Max page size:** 10000 rows per page.\n- **Recommended default parameters:** Page size equals to 10000 rows per page.\n\nFor more information about the API connection, see [Google Ads API documentation.](https://developers.google.com/google-ads/api/docs/start).\n\nAccount authentication\n----------------------\n\nFollow these steps to set up account authentication:\n\n1. In the [Google Cloud console](https://console.cloud.google.com), click **Navigation menu** \\\u003e **API \\& Services** \\\u003e **Credentials** \\\u003e **Create credentials**.\n2. Create a **OAuth Client ID** credential with the following characteristics.\n For more information, see [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2/).\n\n Application type: \"Web Application\"\n Name: \u003cvar translate=\"no\"\u003eCHOSEN_NAME\u003c/var\u003e #(For example,\"Cortex Authentication Client\").\n Authorized redirect URIs: http://127.0.0.1\n\n Replace \u003cvar translate=\"no\"\u003eCHOSEN_NAME\u003c/var\u003e with the chosen name for\n OAuth Client ID credential account.\n3. Save the `Client ID` and `Client secret` after the credential is configured.\n You need it later.\n\n4. Generate a fresh token using [OAuth 2.0 Access Google APIs](https://developers.google.com/identity/protocols/oauth2#5.-refresh-the-access-token,-if-necessary). Cortex Data\n Foundation automatically detects and ingest data from all customers\n (accounts) that are accessible to the credentials used to generate the token.\n\n5. Create a *secret* using Secret Manager:\n\n - In the [Google Cloud console](https://console.cloud.google.com), click **Secret Manager.**\n - Create a secret called `cortex-framework-google-ads-yaml` using the following format and changing the values according with your settings:\n\n {\"developer_token\": \"\u003cvar translate=\"no\"\u003eDEVELOPER_TOKEN_VALUE\u003c/var\u003e\", \"refresh_token\": \"\u003cvar translate=\"no\"\u003eREFRESH_TOKEN_VALUE\u003c/var\u003e\", \"client_id\": \"\u003cvar translate=\"no\"\u003eCLIENT_ID_VALUE\u003c/var\u003e\", \"client_secret\": \"\u003cvar translate=\"no\"\u003eCLIENT_SECRET_VALUE\u003c/var\u003e\", \"use_proto_plus\": False}\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eDEVELOPER_TOKEN_VALUE\u003c/var\u003e with the developer token value available in Google Ads account.\n- \u003cvar translate=\"no\"\u003eREFRESH_TOKEN_VALUE\u003c/var\u003e with the refresh token value obtained in step 4.\n- \u003cvar translate=\"no\"\u003eCLIENT_ID_VALUE\u003c/var\u003e with the client ID value obtained in the OAuth setup in step 2.\n- \u003cvar translate=\"no\"\u003eCLIENT_SECRET_VALUE\u003c/var\u003e with the client secret value obtained from the OAuth setup in step 2.\n\nData Freshness and Delay\n------------------------\n\nAs a general rule, data freshness for Cortex Framework data\nsources is limited by what upstream connection allows for, as well as the\nfrequency of your DAG execution. Adjust your DAG execution frequency to align\nwith upstream frequency, resource constraints, and your business needs.\n\nData retrieved using [Google Ads API](#api_connection)\nis generally available with 3+ hour latency. They may be adjusted afterwards\ndue to conversions and invalid traffic detection. For more information, see\nthe following [About data freshness](https://support.google.com/google-ads/answer/2544985)\narticle in the Google Ads Help Center.\n\nCloud Composer connections permissions\n--------------------------------------\n\nCreate the following connections in Cloud Composer. See more details in the\n[Manage Airflow connections documentation](/composer/docs/how-to/managing/connections).\n\nCloud Composer service account permissions\n------------------------------------------\n\nGrant Dataflow permissions to the service account used in\nCloud Composer (as configured in the `googleads_raw_dataflow`\nconnection). See instructions in [Dataflow documentation](/dataflow/docs/concepts/security-and-permissions#df-service-account).\n\nIngestion settings\n------------------\n\nControl `Source to Raw` and `Raw to CDC` data pipelines through the\nsettings in the file [src/GoogleAds/config/ingestion_settings.yaml](https://github.com/GoogleCloudPlatform/cortex-data-foundation/tree/main/src/marketing/src/GoogleAds/config/ingestion_settings.yaml). This section describes the parameters of\neach data pipeline.\n\n### Source to raw tables\n\nThis section describes which entities are fetched by APIs and how. Each entry\ncorresponds with one Google Ads entity. Based on this config,\nCortex creates Airflow DAGs that run Dataflow pipelines to fetch data\nusing Google Ads APIs.\n\nThe following parameters control the settings for `Source to Raw`\nfor each entry:\n\n### Raw to CDC tables\n\nThis section describes which entries control how data is moved from\nraw tables to CDC tables. Each entry corresponds with a raw table\n(which in turn corresponds with Google Ads API entity as mentioned).\n\nThe following parameters control the settings for `Raw to CDC` for each entry:\n\nReporting settings\n------------------\n\nYou can configure and control how Cortex Framework generates\ndata for the Google Ads final reporting layer using the reporting\nsettings file [src/GoogleAds/config/reporting_settings.yaml](https://github.com/GoogleCloudPlatform/cortex-data-foundation/tree/main/src/marketing/src/GoogleAds/config/reporting_settings.yaml).\nThis file controls\nhow reporting layer BigQuery objects\n(tables, views,functions or stored procedures) are generated.\n\nFor more information, see [Customizing reporting settings file](/cortex/docs/deployment-step-five#customizing_reporting_settings_file).\n\nWhat's next?\n------------\n\n- For more information about other data sources and workloads, see [Data sources and workloads](/cortex/docs/data-sources-and-workloads).\n- For more information about the steps for deployment in production environments, see [Cortex Framework Data Foundation deployment prerequisites](/cortex/docs/deployment-prerequisites)."]]
