配置

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。

调整 MaxReceiveMessageLengthInBytesMaxMetadataSizeInBytes 设置以修复某些 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:设置为 APPLICATIONSERVICE_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。设置时不应使用连字符 (-)。详细了解已关联的账号