使用 dlt Ads 认证源加载广告账户数据：从凭据配置到自定义管线实战
【免费下载链接】dlt data load tool (dlt) is an open that makes data easy ️
项目地址:
Ads 是 的数字广告服务，本指南基于 dlt 的 Ads 认证源（ ），讲解如何通过 " Ads API" 将 、、、 等核心维度数据加载到任意目标数据库（），内容覆盖服务账号与 OAuth 两种认证方式、.toml 完整配置、dlt init 初始化流程、管线运行验证，以及基于源码级 API 的自定义管线开发，让读者能够从零搭建一套可运行、可扩展的 Ads 数据加载管线。
::: 使用提醒 由于获取 Ads API 凭据存在一定门槛，dlt 团队难以对该认证源进行周期性回归测试。该源在创建时已验证可用，并被社区广泛使用；考虑到 在 API 版本管理上的良好实践，可以预期该源在较长周期内稳定运行。 :::
认证源概览：能加载哪些数据
Ads（ 为核心抽象： 聚合多个 ，每个 对应一张目标表。
该认证源可加载的 如下：
名称说明
付费投放广告的企业或个人（广告主客户）
广告组与广告的结构化集合（广告系列）
对账户广告、广告系列及相关设置的修改记录
由给定账户管理的子账户集合
认证方式选择与凭据获取
访问 Ads 认证源首先需要一个开发者令牌（ token），它是连接 Ads API 的必需凭证。获取令牌后，可以选择以下两种认证方式之一：
一般原则是：需要用户同意时优先 OAuth，纯服务端交互时优先服务账号。
创建 GCP 服务账号凭据
若尚无 GCP 服务账号，按以下步骤创建并获取 JSON 密钥：
登录 。按需。启用 " Ads API"，详细流程参考 官方文档。生成凭据： 在控制台左侧面板进入 IAM & Admin，选择 。找到目标服务账号，点击 "" 列下的三点菜单。选择 " Keys" > "ADD KEY" > ""，创建新的 JSON 密钥。下载生成的 .json 文件，其中包含后续配置所需的凭据信息。 创建 OAuth 凭据
若采用 OAuth 认证，按以下步骤在 GCP 中创建桌面应用凭据：
确保 GCP 账户所用邮箱可访问目标 GA4 属性（文档原文要求，实际操作中以能访问对应广告账户为准）。
在 GCP 账户中打开一个 GCP 项目。
在该项目中启用 Ads API。
在搜索栏搜索 "" 并进入 页面。
进入 -> OAuth ID， type 选择 App，并命名。
下载凭据文件，将其中的 、、 填入 .toml。
返回 ，在左侧进入 OAuth 。
填写 App name、用户支持邮箱、授权域名（）、开发者联系邮箱。
添加如下 scope：
"https://www.googleapis.com/auth/adwords"
将你的邮箱添加为测试用户（test user）。
在 .toml 中配置好 、、 后，从项目根目录运行以下脚本生成 token：
python google_ads/setup_script_gcp_oauth.py
脚本会引导完成浏览器授权，授权完成后会输出一个 token，将其填入 .toml 即可。
向 API 共享 Ads 账户
:::note 服务账号认证使用服务账号的 ；OAuth 认证使用创建应用及生成 token 时关联的邮箱。 :::
登录你的 Ads 账户。选择要访问的 Ads 账户。点击右上角的 "Tools & " 图标。在 "Setup" 下选择 " "。点击蓝色 "+" 图标添加新用户。输入服务账号邮箱（服务账号认证）或创建应用/生成 token 时使用的邮箱（OAuth 认证）。设置访问级别：仅需读取数据时 "Read-only" 通常足够；若使用服务账号，可能需要授予 "Admin" 权限，因为服务账号执行的任务通常需要更高权限。点击 "Send " 完成邀请流程。 初始化认证源并配置凭据 使用 dlt init 初始化项目
在终端执行：
dlt init google_ads duckdb
该命令（详见 命令行接口文档）会以 Ads 为 、以 为 初始化示例管线。如需其他目标，将 替换为目标名称即可。命令执行后会在工作目录创建所需的源文件与配置文件（如 .py、.dlt/.toml、.txt）。
在 .toml 中配置凭据
.dlt 目录下的 .toml 用于存放访问令牌等敏感信息，务必妥善保管、切勿提交到版本库。首先配置开发者令牌、客户 ID 与模拟邮箱：
[sources.google_ads]
dev_token = "please set me up!"
customer_id = "please set me up!"
impersonated_email = "please set me up"
接下来，服务账号认证配置如下：
[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!
从中复制 、、 填入上述字段。
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!
最后，按 文档 为目标配置相应的目的地凭据（如 可参考 .md 安装 pip "dlt"）。
凭据类型的源码级解析机制
从源码看， 的 参数类型为 | 的联合类型，二者定义于 dlt///specs/.py：
dlt..value 表示该参数从 提供器（如 .toml）自动注入，这是 dlt 配置注入机制的标准用法。
运行管线
安装依赖：
pip install -r requirements.txt
运行示例管线：
python google_ads_pipeline.py
验证加载结果：
dlt pipeline show
示例管线中 为 ine，也可使用自定义名称。dlt show 命令的完整说明见 。更详细的运行流程可参考 如何运行管线指南。
与 详解
dlt 基于 与 的原理工作： 是若干 的集合， 定义具体的数据提取逻辑。
是一个 @dlt.() 装饰的函数，返回包含元数据、字段与指标数据的 列表：
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.
"""
上述三个参数均声明为 dlt..value，与 .toml 中
.
段及
..
段的键一一对应。
从 Ads 项目拉取报表的全部维度数据：
@dlt.resource(write_disposition="replace")
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.
"""
类似地，、、 三个 函数分别填充各自的维度表。dlt 会依据 名称将数据映射到同名目标表。
自定义管线
如需构建自己的管线，可直接复用认证源中的 与 方法。
配置
pipeline = dlt.pipeline(
pipeline_name="dlt_google_ads_pipeline", # 可使用自定义名称
destination="duckdb", # 选择合适的 destination（如 duckdb、redshift、postgres 等）
dataset_name="full_load_google_ads" # 可使用自定义名称
)
管线配置的详细说明见 文档。 支持 dlt 的全部目标，例如 、、、 等。
加载全部维度
data_default = google_ads()
info = pipeline.run(data=[data_default])
print(info)
仅加载指定
data_selected = google_ads().with_resources("customers", "campaigns")
info = pipeline.run(data=[data_selected])
print(info)
是 的便捷方法，用于只加载指定的 子集，避免拉取不需要的表。从 文档 可以看到，该方法也被其他认证源（如 、、 等）广泛使用，是控制加载范围的标准做法。注意原文档示例中 .run(data=
) 与 略有出入，实际使用时应传入 。
.run 会依次执行提取（）、规范化（）与加载（load）三个阶段，将 产出的事件数据写入目标数据库；返回的 info 对象包含加载统计信息（如加载包 ID、各表行数等），打印后即可确认执行结果。
深入阅读
【免费下载链接】dlt data load tool (dlt) is an open that makes data easy ️
项目地址:
云衔科技是一家专注于企业数字化广告营销解决方案的服务商。公司凭借深厚的行业经验和专业技术能力，致力于为企业客户提供全方位、更高效的数字化广告营销与运营服务。