Google Ads API .NET/C 客户端库快速上手：GoogleAdsConfig 运行时初始化与首个 Campaign 查询实战-港品优选

Google Ads API .NET/C# 客户端库快速上手：GoogleAdsConfig 运行时初始化与首个 Campaign 查询实战

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本指南以当前仓库中 google-ads-api-quickstart 技能的 .NET 参考文档 references/dotnet.md 为主体，系统讲解如何用 .NET/C# 完成 Google Ads API 的环境搭建、凭据配置与首次调用。读完本文，你将掌握通过 NuGet 安装官方Google.Ads.GoogleAds客户端库、用GoogleAdsConfig对象在运行时注入凭据、以及用SearchStream流式查询 Campaign 列表的完整实战链路。

一、前置条件：.NET SDK 与 NuGet

在开始之前，需要确认两样基础环境：

.NET SDK：具体的最低支持版本需要动态查询官方"Supported Client Library Versions"页面后确定，不要硬编码某个历史版本号。在本技能的 SKILL.md 中，为无网络场景提供了离线兜底值：.NET 6.0+，可作为最低安全版本参考。
包管理器：NuGet，随 .NET SDK 一并安装。

版本动态解析是整套 Quickstart 技能的核心约束之一（详见 SKILL.md 中 "Dynamic Version Resolution" 一节）：所有客户端库模板中的VXX占位符，都必须在生成代码前替换为首字母大写的 API 版本号（例如v24→V24），以保证命名空间与官方发布的当前稳定版本一致。

二、Step 1：通过 NuGet 安装官方客户端库

在项目目录下执行以下命令，安装官方 .NET 客户端库：

dotnet add package Google.Ads.GoogleAds

该包即为 .NET 生态下对接 Google Ads API 的官方载体（对应技能中的"Package:Google.Ads.GoogleAds"）。安装完成后，项目文件（.csproj）中会自动出现对应的PackageReference条目。

如果后续希望改用外部配置文件或环境变量来管理凭据（而不是在代码里硬编码），还需要额外安装配套扩展包：

dotnet add package Google.Ads.GoogleAds.Extensions

该扩展包提供了从环境变量、App.config或 JSON 配置根对象加载设置的 API（详见下文 Step 2）。

三、Step 2：凭据配置——GoogleAdsConfig 运行时初始化

.NET 客户端库推荐的配置方式是：在程序运行时构建一个GoogleAdsConfig对象，将凭据直接注入其中。在写代码前，请先准备好以下凭据项：

凭据	说明	是否必填
`DeveloperToken`	开发者令牌，标识你的开发者访问权与 API 配额	必填
`OAuth2ClientId`	OAuth2 客户端 ID，标识你的应用	必填
`OAuth2ClientSecret`	OAuth2 客户端密钥	必填
`OAuth2RefreshToken`	刷新令牌，用于自动续期访问令牌	必填
`LoginCustomerId`	登录客户 ID，当以经理账户（Manager Account）身份认证、且目标是其子账户时必填	选填（按场景）

关于这些凭据的获取流程（Developer Token 来自 Google Ads 经理账户的API Center；OAuth2 Client ID/Secret 需要在 Google Cloud Console 中启用 Google Ads API 并创建 Desktop App 类型的 OAuth 客户端；Refresh Token 通过gcloud auth application-default login携带adwordsscope 生成），以及"待审批令牌只能访问测试账户"等关键限制，都已在 SKILL.md 的 "Step 1: Obtain Google Ads API Credentials" 中详细展开，配置 .NET 环境前建议先完整阅读。

3.1 运行时初始化（推荐）

GoogleAdsConfig config = new GoogleAdsConfig() { DeveloperToken = "INSERT_DEVELOPER_TOKEN_HERE", OAuth2Mode = OAuth2Flow.APPLICATION, OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE", OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE", OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE", // LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE" };

其中OAuth2Mode = OAuth2Flow.APPLICATION表示采用"已安装应用"（Desktop App）的 OAuth2 授权流程，与凭据获取阶段创建的 OAuth 客户端类型（Desktop App）保持一致。LoginCustomerId默认注释掉，只有通过经理账户访问子账户时才需要取消注释并填入10 位经理账户 ID。

3.2 备选配置方式：外部配置与配置根对象

如果你倾向于把凭据放在配置文件或环境变量中，需要引入前面提到的Google.Ads.GoogleAds.Extensions扩展包，然后显式将设置加载到GoogleAdsConfig对象上，支持三种来源：

环境变量：调用config.LoadFromEnvironmentVariables();
App.config：调用config.LoadFromDefaultAppConfigSection();
settings.json / 自定义 JSON：先用ConfigurationBuilder构建配置根对象，再调用config.LoadFromConfigurationRoot(configRoot);

这种设计的好处是凭据不再散落在代码里，便于按环境（开发/生产）切换。三种加载方式也可与运行时初始化叠加使用——例如先构造基础GoogleAdsConfig，再用环境变量覆盖其中个别字段（Quickstart 代码中便保留了这样一行可选调用：config.LoadFromEnvironmentVariables();）。

四、Step 3：编写并运行 Quickstart 脚本

创建Program.cs，内容如下。有两个关键点需要特别留意：

客户 ID 必须清洗：在把 Client Customer ID 传给 API 之前，必须通过Replace("-", "")去掉所有连字符（例如把123-456-7890转为1234567890），以保证标准数值解析。
替换 VXX 占位符：using命名空间与Services.VXX.GoogleAdsService中的VXX必须替换为前置步骤中动态解析出的首字母大写 API 版本号（例如V24），对应映射规则见 SKILL.md 的 Placeholder Mapping Table（.NET/C# 命名空间 → 首字母大写版本号）。

using System; using Google.Ads.GoogleAds.Config; using Google.Ads.GoogleAds.Lib; using Google.Ads.GoogleAds.VXX.Services; using Google.Ads.GoogleAds.VXX.Errors; class Program { static void Main(string[] args) { if (args.Length < 1) { Console.WriteLine("Usage: dotnet run <CUSTOMER_ID>"); return; } // Clean customer ID by stripping hyphens string customerId = args[0].Replace("-", ""); GoogleAdsConfig config = new GoogleAdsConfig() { DeveloperToken = "INSERT_DEVELOPER_TOKEN_HERE", OAuth2Mode = OAuth2Flow.APPLICATION, OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE", OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE", OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE", // LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE" }; // Optional: If using Google.Ads.GoogleAds.Extensions, you can also load overriding environment variables: // config.LoadFromEnvironmentVariables(); GoogleAdsClient client = new GoogleAdsClient(config); GoogleAdsServiceClient service = client.GetService(Services.VXX.GoogleAdsService); string query = "SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id"; try { service.SearchStream(customerId, query, delegate(SearchGoogleAdsStreamResponse response) { foreach (GoogleAdsRow row in response.Results) { Console.WriteLine($"Campaign found: ID = {row.Campaign.Id}, Name = '{row.Campaign.Name}', Status = {row.Campaign.Status}"); } }); } catch (GoogleAdsException ex) { Console.WriteLine($"Request failed: ID {ex.RequestId}. Error: {ex.Message}"); } } }

这段代码的运行链路可以拆解为四步：

构建客户端：new GoogleAdsClient(config)依据GoogleAdsConfig完成 OAuth2 凭据装载与 API 端点初始化；
获取服务：client.GetService(Services.VXX.GoogleAdsService)返回对应 API 版本下的GoogleAdsServiceClient；
提交 GAQL 查询：查询语句SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id是标准的 Google Ads Query Language，用于按 ID 排序取出所有广告系列；
流式消费结果：SearchStream通过委托回调逐批处理SearchGoogleAdsStreamResponse，每行结果对应一个GoogleAdsRow，从中读取Campaign的 Id、Name 与 Status 字段。

出错时，GoogleAdsException会携带RequestId与错误详情，便于向 Google 支持团队提交排查。

运行项目（将XXXXXXXXXX替换为你的10 位 Client Customer ID）：

dotnet run XXXXXXXXXX

五、Step 4：验证输出

一次成功的执行会把该客户 ID 下关联的广告系列流式输出到控制台，输出形如：

Campaign found: ID = 987654321, Name = 'Interstate Search Promo', Status = Enabled Campaign found: ID = 555444333, Name = 'Local Brand Awareness', Status = Paused

只要能看到Campaign found:开头的行，就说明从凭据校验、API 版本匹配到 GAQL 查询的整条链路已经打通，这是你的第一笔真实 Google Ads API 调用。

六、常见错误与排查要点

Quickstart 技能在 SKILL.md 的 "Step 4: Troubleshooting Common Errors" 中总结了 .NET 环境同样适用的两个高频错误，配置与运行前建议对照自查。

6.1`USER_PERMISSION_DENIED`：缺少 login_customer_id

症状：执行请求（如检索广告系列）时收到USER_PERMISSION_DENIED。
根因：认证所用的 OAuth2 用户是通过经理账户间接访问目标子账户的，但请求头里缺少经理账户的 ID。
修复：在GoogleAdsConfig中把 10 位经理账户 ID 填入LoginCustomerId（对应其他语言配置中google-ads.yaml的login_customer_id字段）。其路由逻辑是：login_customer_id告诉 API 将 OAuth 凭据经经理账户路由，从而校验对子账户的访问权；client_customer_id则指向真正的目标子账户。在经理-子账户层级关系中留空login_customer_id，是权限错误的第一大诱因。

6.2`DEVELOPER_TOKEN_NOT_APPROVED`：待审批令牌只能访问测试账户

症状：脚本报DEVELOPER_TOKEN_NOT_APPROVED。
根因：Developer Token 处于Pending（未审批）状态，却用于请求生产环境的真实 Google Ads 账户。
修复：待审批令牌功能完整但仅限测试账户；要访问生产账户，令牌必须由 Google Ads API 合规团队审批为Explorer Access、Basic Access或Standard Access三个级别之一。推荐的沙箱做法是：创建测试经理账户（无需审批令牌）→ 在其下创建测试子账户→ 在配置中使用测试子账户的 Customer ID。该限制由 Google 服务端强制实施，客户端任何绕过手段都不会生效。

七、与其他语言轨道的关系

本技能覆盖 Python、Java、.NET、PHP、Ruby、Perl 六种官方客户端库及 REST 直连共七条接入轨道，各轨道遵循完全一致的凭据体系、GAQL 查询语法与版本动态解析约束，仅 API 形态不同：

Python Setup Reference（包名google-ads，基于GoogleAdsClient.load_from_storage与 YAML 配置）
Java Setup Reference（构件com.google.api-ads:google-ads，命名空间为小写版本号v24）
PHP Setup Reference（包名googleads/google-ads-php，命名空间为首字母大写版本号）
Ruby Setup Reference（Gemgoogle-ads-ruby）
Perl Setup Reference（包名Google::Ads::GoogleAds::Client）
REST Setup Reference（原始 HTTP POST JSON，端点为小写版本号路径）

如果你后续的目标是让 AI 助手（如 Gemini、Cursor、Claude Code）通过自然语言查询 Google Ads，则不必手写客户端代码，而应直接切换到同目录下的google-ads-api-mcp-setup技能，安装官方 Google Ads MCP Server 来完成对接——这属于本技能在 SKILL.md "Cross-Referencing" 一节中明确指引的交接路径。

八、小结

从dotnet add package Google.Ads.GoogleAds安装依赖，到GoogleAdsConfig运行时注入五类凭据，再到SearchStream流式输出 Campaign 列表，本文完整还原了 .NET/C# 下 Google Ads API 的 Quickstart 全流程。记住三个核心实践：版本占位符VXX必须动态解析并替换为首字母大写版本号、Client Customer ID 传入前必须去除连字符、经理-子账户层级下务必配置LoginCustomerId。对照 references/dotnet.md 与 SKILL.md 原文实践，即可在十几分钟内跑通第一笔真实查询。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析