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 配额必填OAuth2ClientIdOAuth2 客户端 ID标识你的应用必填OAuth2ClientSecretOAuth2 客户端密钥必填OAuth2RefreshToken刷新令牌用于自动续期访问令牌必填LoginCustomerId登录客户 ID当以经理账户Manager Account身份认证、且目标是其子账户时必填选填按场景关于这些凭据的获取流程Developer Token 来自 Google Ads 经理账户的API CenterOAuth2 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 IDdotnet 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.1USER_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.2DEVELOPER_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命名空间为小写版本号v24PHP Setup Reference包名googleads/google-ads-php命名空间为首字母大写版本号Ruby Setup ReferenceGemgoogle-ads-rubyPerl Setup Reference包名Google::Ads::GoogleAds::ClientREST 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），仅供参考 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 配额必填OAuth2ClientIdOAuth2 客户端 ID标识你的应用必填OAuth2ClientSecretOAuth2 客户端密钥必填OAuth2RefreshToken刷新令牌用于自动续期访问令牌必填LoginCustomerId登录客户 ID当以经理账户Manager Account身份认证、且目标是其子账户时必填选填按场景关于这些凭据的获取流程Developer Token 来自 Google Ads 经理账户的API CenterOAuth2 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 IDdotnet 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.1USER_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.2DEVELOPER_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命名空间为小写版本号v24PHP Setup Reference包名googleads/google-ads-php命名空间为首字母大写版本号Ruby Setup ReferenceGemgoogle-ads-rubyPerl Setup Reference包名Google::Ads::GoogleAds::ClientREST 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），仅供参考