使用 dlt Google Ads 认证源加载广告账户数据从凭据配置到自定义管线实战【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltGoogle Ads 是 Google 的数字广告服务本指南基于 dlt 的 Google Ads 认证源verified source讲解如何通过 Google Ads API 将customers、campaigns、change_events、customer_clients等核心维度数据加载到任意目标数据库destination内容覆盖服务账号与 OAuth 两种认证方式、secrets.toml完整配置、dlt init初始化流程、管线运行验证以及基于源码级 API 的自定义管线开发让读者能够从零搭建一套可运行、可扩展的 Google Ads 数据加载管线。:::warning 使用提醒 由于获取 Google Ads API 凭据存在一定门槛dlt 团队难以对该认证源进行周期性回归测试。该源在创建时已验证可用并被社区广泛使用考虑到 Google 在 API 版本管理上的良好实践可以预期该源在较长周期内稳定运行。 :::认证源概览能加载哪些数据Google Adsads.google.com 为核心抽象source 聚合多个 resource每个 resource 对应一张目标表。该认证源可加载的 resource 如下名称说明customers付费投放广告的企业或个人广告主客户campaigns广告组与广告的结构化集合广告系列change_events对账户广告、广告系列及相关设置的修改记录customer_clients由给定账户管理的子账户集合认证方式选择与凭据获取访问 Google Ads 认证源首先需要一个开发者令牌developer token它是连接 Google Ads API 的必需凭证。获取令牌后可以选择以下两种认证方式之一OAuth 凭据OAuth credentials适用于需要用户授权user consent的场景例如需要以某个用户身份访问其管理的广告账户。服务账号凭据Service account credentials适用于服务器到服务器server-to-server的交互场景例如后台定时任务直接拉取数据。一般原则是需要用户同意时优先 OAuth纯服务端交互时优先服务账号。创建 GCP 服务账号凭据若尚无 GCP 服务账号按以下步骤创建并获取 JSON 密钥登录 console.cloud.google.com。按需创建服务账号。启用 Google Ads API详细流程参考 Google 官方文档。生成凭据在控制台左侧面板进入 IAM Admin选择 Service Accounts。找到目标服务账号点击 Actions 列下的三点菜单。选择 Manage Keys ADD KEY CREATE创建新的 JSON 密钥。下载生成的.json文件其中包含后续配置所需的凭据信息。创建 Google OAuth 凭据若采用 OAuth 认证按以下步骤在 GCP 中创建桌面应用凭据确保 GCP 账户所用邮箱可访问目标 GA4 属性文档原文要求实际操作中以能访问对应广告账户为准。在 GCP 账户中打开一个 GCP 项目。在该项目中启用 Google Ads API。在搜索栏搜索 credentials 并进入 Credentials 页面。进入 Credentials - OAuth client IDApplication type 选择Desktop App并命名。下载凭据文件将其中的client_id、client_secret、project_id填入secrets.toml。返回 Credentials在左侧进入OAuth consent screen。填写 App name、用户支持邮箱、授权域名localhost.com、开发者联系邮箱。添加如下 scopehttps://www.googleapis.com/auth/adwords将你的邮箱添加为测试用户test user。在secrets.toml中配置好client_id、client_secret、project_id后从项目根目录运行以下脚本生成 refresh tokenpython google_ads/setup_script_gcp_oauth.py脚本会引导完成浏览器授权授权完成后会输出一个refresh token将其填入secrets.toml即可。向 API 共享 Google Ads 账户:::note 服务账号认证使用服务账号的client_emailOAuth 认证使用创建应用及生成 refresh token 时关联的邮箱。 :::登录你的 Google Ads 账户。选择要访问的 Google Ads 账户。点击右上角的 Tools Settings 图标。在 Setup 下选择 Account access。点击蓝色 图标添加新用户。输入服务账号邮箱服务账号认证或创建应用/生成 refresh token 时使用的邮箱OAuth 认证。设置访问级别仅需读取数据时 Read-only 通常足够若使用服务账号可能需要授予 Admin 权限因为服务账号执行的任务通常需要更高权限。点击 Send invitation 完成邀请流程。初始化认证源并配置凭据使用 dlt init 初始化项目在终端执行dlt init google_ads duckdb该命令详见 命令行接口文档会以 Google Ads 为 source、以 duckdb 为 destination 初始化示例管线。如需其他目标将duckdb替换为目标名称即可。命令执行后会在工作目录创建所需的源文件与配置文件如google_ads_pipeline.py、.dlt/secrets.toml、requirements.txt。在 secrets.toml 中配置凭据.dlt目录下的secrets.toml用于存放访问令牌等敏感信息务必妥善保管、切勿提交到版本库。首先配置开发者令牌、客户 ID 与模拟邮箱[sources.google_ads] dev_token please set me up! customer_id please set me up! impersonated_email please set me updev_token连接 Google Ads API 所需的开发者令牌。customer_idGoogle Ads 账户唯一的三段式编号格式XXX-XXX-XXXX用于 API 访问与账户操作可在 Google Ads 后台右上角看到。impersonated_email允许通过 API 使用服务账号安全访问 Google Ads 账户同时复用广告平台内特定用户的权限即服务账号模拟该用户。接下来服务账号认证配置如下[sources.google_ads.credentials] project_id project_id # please set me up! client_email client_email # please set me up! private_key private_key # please set me up!从前面下载的.json文件中复制project_id、private_key、client_email填入上述字段。OAuth 认证则替换为从OAuth 凭据获取的值[sources.google_ads.credentials] client_id client_id # please set me up! client_secret client_secret # please set me up! refresh_token refresh_token # please set me up! project_id project_id # please set me up!最后按 destinations 文档 为目标配置相应的目的地凭据如 duckdb 可参考 duckdb.md 安装pip install dlt[duckdb]。凭据类型的源码级解析机制从源码看google_ads的credentials参数类型为GcpOAuthCredentials | GcpServiceAccountCredentials的联合类型二者定义于 dlt/common/configuration/specs/gcp_credentials.pyGcpServiceAccountCredentialsL383-L399持有private_key、private_key_id、client_email、project_id等字段其on_resolved钩子L145-L148会在解析完成后检查private_key是否以换行结尾否则自动补\n因为缺少换行的 PEM 私钥无法被 Crypto 正确解析——这正是secrets.toml中私钥末尾可能被截断时管线仍能运行的原因之一。GcpOAuthCredentialsL403-L409继承自GcpDefaultCredentials与GcpOAuthCredentialsWithoutDefaults后者L174-L320实现了基于requests_oauthlib/google_auth_oauthlib的 token 获取与刷新逻辑无 refresh token 时通过InstalledAppFlow走本地授权流程_get_refresh_token已有 refresh token 时通过OAuth2Session.refresh_token换取 access token_get_access_token。这意味着只要在secrets.toml中填好 refresh token管线运行时会自动完成 access token 刷新无需人工干预。两个凭据类都继承GcpDefaultCredentials其on_partial钩子L360-L373会在配置缺失时尝试从 Google 默认凭据ADC解析进一步降低本地开发配置成本。dlt.secrets.value表示该参数从 secrets 提供器如secrets.toml自动注入这是dlt配置注入机制的标准用法。运行管线安装依赖pip install -r requirements.txt运行示例管线python google_ads_pipeline.py验证加载结果dlt pipeline pipeline_name show示例管线中pipeline_name为dlt_google_ads_pipeline也可使用自定义名称。dlt pipeline show命令的完整说明见 命令行接口文档。更详细的运行流程可参考 如何运行管线指南。Sources 与 resources 详解dlt基于 sources 与 resources 的原理工作source 是若干 resource 的集合resource 定义具体的数据提取逻辑。Sourcegoogle_adsgoogle_ads是一个dlt.source()装饰的函数返回包含元数据、字段与指标数据的 resource 列表from dlt.extract import DltResource from dlt.common.configuration.specs import GcpOAuthCredentials, GcpServiceAccountCredentials dlt.source() def google_ads( credentials: GcpOAuthCredentials | GcpServiceAccountCredentials dlt.secrets.value, impersonated_email: str dlt.secrets.value, dev_token: str dlt.secrets.value, ) - list[DltResource]: Initializes a client with the provided credentials and development token to load default tables from Google Ads into the database. This function returns various resources such as customers, campaigns, change events, and customer clients. credentialsGCP OAuth 或服务账号凭据。impersonated_email通过服务账号利用广告平台内特定用户权限访问 Google Ads 账户的模拟邮箱。dev_token访问 Google Ads API 必需的开发者令牌。上述三个参数均声明为dlt.secrets.value与secrets.toml中[sources.google_ads]段及[sources.google_ads.credentials]段的键一一对应。Resourcecustomerscustomersresource 从 Google Ads 项目拉取报表的全部维度数据dlt.resource(write_dispositionreplace) def customers( client: Resource, customer_id: str dlt.secrets.value ) - Iterator[TDataItem]: Fetches customer data from the Google Ads service and yields each customer as a dictionary. client用于与 Google 服务交互的 Google API Resource 对象。customer_idGoogle Ads 账户的唯一标识符。write_dispositionreplace每次全量加载时以替换方式写入目标表关于写入策略的更多细节可参考 write_disposition 相关文档 或增量加载文档。类似地campaigns、change_events、customer_clients三个 resource 函数分别填充各自的维度表。dlt 会依据 resource 名称将数据映射到同名目标表。自定义管线如需构建自己的管线可直接复用认证源中的 source 与 resource 方法。配置 pipelinepipeline dlt.pipeline( pipeline_namedlt_google_ads_pipeline, # 可使用自定义名称 destinationduckdb, # 选择合适的 destination如 duckdb、redshift、postgres 等 dataset_namefull_load_google_ads # 可使用自定义名称 )管线配置的详细说明见 pipeline 文档。destination支持 dlt 的全部目标例如 duckdb、postgres、redshift、snowflake 等。加载全部维度data_default google_ads() info pipeline.run(data[data_default]) print(info)仅加载指定 resourcedata_selected google_ads().with_resources(customers, campaigns) info pipeline.run(data[data_selected]) print(info)with_resources是 source 的便捷方法用于只加载指定的 resource 子集避免拉取不需要的表。从 source 文档 可以看到该方法也被其他认证源如 mongodb、facebook_ads、zendesk 等广泛使用是控制加载范围的标准做法。注意原文档示例中pipeline.run(data[data_default])与data_selected略有出入实际使用时应传入data_selected。pipeline.run会依次执行提取extract、规范化normalize与加载load三个阶段将 resource 产出的事件数据写入目标数据库返回的info对象包含加载统计信息如加载包 ID、各表行数等打印后即可确认执行结果。深入阅读Sources 与 resources 概念 / resource 文档如何运行管线pipelines 文档命令行接口全部认证源列表destinations 列表凭据类型实现dlt/common/configuration/specs/gcp_credentials.py【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考