Google Ads API 客户端库提供了多种配置设置,可用于自定义库行为。
在运行时配置库
配置客户端库的首选方法是在运行时初始化 GoogleAdsConfig
对象:
GoogleAdsConfig config = new GoogleAdsConfig()
{
DeveloperToken = "******",
OAuth2Mode = "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 中的构建规则
最后,将新的配置文件添加到项目中。将此文件的属性更改为始终复制到输出文件夹。
现在,构建并运行您的项目。您的应用将开始从新配置文件中提取值。
使用自定义 JSON 文件进行配置
您可以使用 IConfigurationRoot
实例来配置客户端库。
创建 JSON 文件
创建一个名为 GoogleAdsApi.json
且结构与 App.config
文件类似的 JSON 文件。
{
"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
可避免此错误。请注意,该错误还表示您的代码处理了非常大的 Response 对象(例如大型
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。设置时不应使用连字符 (-
)。详细了解已关联的账号。