Google Ads API 客户端库提供了多项配置设置,可用于自定义库的行为。
在运行时配置库
配置客户端库的首选方法是在运行时初始化 GoogleAdsConfig
对象:
GoogleAdsConfig config = new GoogleAdsConfig()
{
DeveloperToken = "******",
OAuth2Mode = OAuth2Flow.APPLICATION,
OAuth2ClientId = "******.apps.googleusercontent.com",
OAuth2ClientSecret = "******",
OAuth2RefreshToken = "******"
};
GoogleAdsClient client = new GoogleAdsClient(config);
备用配置选项
我们还提供了一些其他选项来配置客户端库:要启用这些选项,请在项目中添加对 Google.Ads.GoogleAds.Extensions
软件包的 Nuget 引用。
如果您使用这些选项之一,则系统不会自动选择配置设置:您应按如下方式明确加载它们。
使用 App.config 进行配置
特定于 Google Ads API
的所有设置都存储在 App.config
文件的 GoogleAdsApi
节点中。典型配置 App.config
如下所示:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="GoogleAdsApi" type="System.Configuration.DictionarySectionHandler" />
</configSections>
<GoogleAdsApi>
<!-- Set the service timeout in milliseconds. -->
<add key="Timeout" value="2000" />
<!-- Proxy settings for library. -->
<add key="ProxyServer" value="http://localhost:8888"/>
<add key="ProxyUser" value=""/>
<add key="ProxyPassword" value=""/>
<add key="ProxyDomain" value=""/>
<!-- API-specific settings -->
<add key="DeveloperToken" value="******"/>
<!-- OAuth2 settings -->
<add key = "OAuth2Mode" value="APPLICATION"/>
<add key = "OAuth2ClientId" value = "******.apps.googleusercontent.com" />
<add key = "OAuth2ClientSecret" value = "******" />
<add key = "OAuth2RefreshToken" value = "******" />
</GoogleAdsApi>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
</startup>
</configuration>
如需从 App.config
文件加载配置设置,请对 GoogleAdsConfig
对象调用 LoadFromDefaultAppConfigSection
方法:
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);
指定单独的 App.config 文件
如果您不希望 App.config
杂乱无章,可以使用 configSource
属性将特定于库的配置移至其自己的配置文件中。
第 1 步:在 App.config 中指定 configSource
将您的 App.config
修改为如下所示:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="GoogleAdsApi" type="System.Configuration.DictionarySectionHandler"/>
</configSections>
<GoogleAdsApi configSource="GoogleAdsApi.config"/>
...
</configuration>
第 2 步:指定配置文件的内容
现在,使用您在 configSource
中指定的名称创建另一个配置文件,并将配置节点从 App.config
移至此文件中:
<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
... More settings.
</GoogleAdsApi>
第 3 步:修复 csproj 中的构建规则
最后,在项目中添加新的配置文件。请将此文件的属性更改为 Always copy to output folder。
现在,构建并运行您的项目。您的应用将开始从新配置文件中获取值。
使用自定义 JSON 文件的配置
您可以使用 IConfigurationRoot
实例来配置客户端库。
创建 JSON 文件
创建一个名为 GoogleAdsApi.json
的 JSON 文件,其结构与 App.config
文件类似。
{
"Timeout": "2000",
"ProxyServer": "http://localhost:8888",
"ProxyUser": "",
"ProxyPassword": "",
"ProxyDomain": "",
"DeveloperToken": "******",
"OAuth2Mode": "APPLICATION",
"OAuth2ClientId": "******.apps.googleusercontent.com",
"OAuth2ClientSecret": "******",
"OAuth2RefreshToken": "******",
}
加载配置
接下来,将 JSON 文件加载到 IConfigurationRoot
中。
ConfigurationBuilder builder = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);
使用 settings.json 进行配置
上述过程与使用自定义 JSON 类似,只不过键应位于名为 GoogleAdsApi
的部分中:
{
"GoogleAdsApi":
{
"DeveloperToken": "******",
"OAuth2Mode": "APPLICATION",
"OAuth2ClientId": "******.apps.googleusercontent.com",
"OAuth2ClientSecret": "******",
"OAuth2RefreshToken": "******",
...
}
// More settings...
}
接下来,您可以在页面中使用 IConfiguration
实例:
IConfigurationSection section = Configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);
使用环境变量进行配置
您还可以使用环境变量初始化 GoogleAdsClient
:
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);
请参阅支持的环境变量的完整列表。
配置字段
以下是 Google Ads .NET 库支持的设置列表。
互联网连接设置
Timeout
:使用此键可设置服务超时(以毫秒为单位)。默认值是根据 googleads_grpc_service_config.json 中的method_config/timeout
设置设定的。如果您需要对 API 调用的最长时间施加较短的限制,请设置一个较低的值。您可以将超时设置为 2 小时或更长时间,但 API 仍可能会使长时间运行的请求超时并返回DEADLINE_EXCEEDED
错误。ProxyServer
:如果您使用代理连接到互联网,请将此项设置为 HTTP 代理服务器网址。ProxyUser
:将此项设置为您针对代理服务器进行身份验证所需的用户名。如果不需要用户名,请将其留空。ProxyPassword
:如果您为ProxyUser
设置了值,则将此项设为ProxyUser
的密码。ProxyDomain
:如果您的代理服务器要求进行设置,请将此项设置为ProxyUser
的网域。MaxReceiveMessageLengthInBytes
:使用此设置可以增加客户端库可以处理的 API 响应的大小上限。默认值为 64 MB。MaxMetadataSizeInBytes
:使用此设置可以增加客户端库可以处理的 API 错误响应的大小上限。默认值为 16 MB。
调整
MaxReceiveMessageLengthInBytes
和MaxMetadataSizeInBytes
设置以修复某些ResourceExhausted
错误。这些设置可解决Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)"
形式的错误。在此示例中,错误是由于消息大小 (
423184132 bytes
) 大于库可以处理的大小 (67108864 bytes
)。请将MaxReceiveMessageLengthInBytes
增加到500000000
以避免此错误。请注意,该错误还表示您的代码处理了一个非常大的响应对象(例如大型
SearchGoogleAdsResponse
)。由于 .NET 的大对象堆,这可能会导致代码性能受到影响。如果这会带来性能方面的顾虑,那么您可能需要探索如何重新组织 API 调用或重新设计应用的各个部分。
OAuth2 设置
使用 OAuth2 授权您对 Google Ads API 服务器的调用时,您应设置以下配置键:
AuthorizationMethod
:设置为OAuth2
。OAuth2Mode
:设置为APPLICATION
或SERVICE_ACCOUNT
。OAuth2ClientId
:将此值设置为您的 OAuth2 客户端 ID。OAuth2ClientSecret
:将此值设置为您的 OAuth2 客户端密钥。OAuth2Scope
:如果要为多个 API 授权 OAuth2 令牌,请将此值设置为不同的范围。此设置是可选的。
如果您使用的是 OAuth2Mode == APPLICATION
,则需要设置下面这些额外的配置键。
OAuth2RefreshToken
:如果要重复使用 OAuth2 令牌,请将此值设置为预先生成的 OAuth2 刷新令牌。此设置是可选的。OAuth2RedirectUri
:将此值设置为 OAuth2 重定向网址。此设置是可选的。
如需了解详情,请参阅以下指南:
如果您使用的是 OAuth2Mode == SERVICE_ACCOUNT
,则需要设置以下额外的配置键。
OAuth2PrnEmail
:将此值设置为您要模拟的帐号的电子邮件地址。OAuth2SecretsJsonPath
:将此值设置为 OAuth2 JSON 配置文件路径。
如需了解详情,请参阅 OAuth 服务帐号流程指南。
交通设置
UseGrpcCore
:将此设置设为true
可将Grpc.Core
库用作底层传输层。如需了解详情,请参阅 gRPC 支持指南。
Google Ads API 设置
以下设置特定于 Google Ads API。
DeveloperToken
:将此项设置为您的开发者令牌。LoginCustomerId
:这是在请求中使用的授权客户的客户 ID,不带连字符 (-
)。LinkedCustomerId
:仅当通过 Google Ads 界面中关联的帐号(Google Ads API 中的AccountLink
资源)获得权限时,更新实体资源的方法才需要此标头。将此值设置为更新指定客户 ID 的资源的数据提供商的客户 ID。设置时不应使用连字符 (-
)。详细了解关联的账号。