配置

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 中的 build 规则

最后，在项目中添加新的配置文件。将此文件的属性更改为始终复制到输出文件夹。

现在，构建并运行您的项目。您的应用将开始从新配置文件中获取值。

使用自定义 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);

请参阅受支持的环境变量的完整列表。

使用通用流

您还可以从通用流（包括加密流）加载配置或部分配置：

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  DeveloperToken = "******",
  OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file.

CryptoStream strm = ....

StreamReader rdr = new StreamReader(strm);
// Configure the OAuth credentials from the encrypted file.
config.LoadOAuth2SecretsFromStream(rdr);

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。应不含连字符 (-)。详细了解关联账号。