配置

Google Ads API 客户端库提供了多项配置设置，可用于自定义库行为。

在运行时配置库

配置客户端库的首选方法是在运行时初始化 GoogleAdsConfig 对象：

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

备用配置选项

该库还提供了其他选项，用于从 appsettings.json、自定义 JSON 文件、环境变量或 App.config 加载配置设置。如需启用这些功能，请在项目中安装 Google.Ads.GoogleAds.Extensions NuGet 软件包：

dotnet add package Google.Ads.GoogleAds.Extensions

如果您使用其中一个选项，系统不会自动获取配置设置；您必须明确加载这些设置，如以下部分所示。从外部文件或数据流加载设置时，请务必处理文件 I/O 异常（例如 FileNotFoundException 或 UnauthorizedAccessException）。

使用 appsettings.json 或 settings.json

在 .NET 8.0 和 ASP.NET Core 应用中，将配置键放在 appsettings.json（或 settings.json）中的 GoogleAdsApi 部分：

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

接下来，从应用的 IConfiguration 实例（例如，由 ASP.NET Core 注入或使用 ConfigurationBuilder 构建）中提取 GoogleAdsApi 部分，并使用 LoadFromConfigurationSection 加载该部分：

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

或者，您也可以使用 LoadFromSettingsJson 直接按路径加载 appsettings.json 或 settings.json 文件：

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

您还可以通过调用 config.TryLoadFromEnvironmentFilePath 从 GOOGLE_ADS_CONFIGURATION_FILE_PATH 环境变量 (EnvironmentVariableNames.CONFIG_FILE_PATH) 加载路径。

使用自定义 JSON 文件

您还可以使用 IConfigurationRoot 实例加载不含顶级 GoogleAdsApi 部分的平面 JSON 文件。

创建一个 JSON 文件

创建一个名为 GoogleAdsApi.json 的 JSON 文件，用于在根级别定义配置键：

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

加载配置

接下来，将 JSON 文件加载到 IConfigurationRoot 中：

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

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);

使用环境变量

您还可以使用环境变量初始化 GoogleAdsClient：

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

注意 ：由于 GoogleAdsConfig.OAuth2Mode 默认为 APPLICATION，因此在使用 GOOGLE_ADS_JSON_KEY_FILE_PATH 通过服务账号进行身份验证时，请务必同时设置 GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT。

查看支持的环境变量的完整列表。

使用 App.config

在 .NET Framework 应用中，所有特定于 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="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

如需从 App.config 文件加载配置设置，请对 GoogleAdsConfig 对象调用 LoadFromDefaultAppConfigSection 方法：

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

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 (GoogleAdsApi.config) 中指定的名称创建另一个配置文件，并将 GoogleAdsApi 配置节点从 App.config 移至此文件：

   <?xml version="1.0" encoding="utf-8" ?>
   <GoogleAdsApi>
     <!-- More settings. -->
   </GoogleAdsApi>
   

3. 更新 .csproj 中的 build 规则。在项目中添加新的配置文件，并将其复制到输出目录属性设置为始终复制。重新构建并运行项目，以便应用从新配置文件中获取值。

使用通用直播

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

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

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    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，以避免此错误。请注意，该错误还表明您的代码处理了非常大的响应对象（例如大型 SearchGoogleAdsResponse）。由于 .NET 的大对象堆，这可能会对代码的性能产生影响。如果这成为性能问题，您可能需要探索如何重新组织 API 调用或重新设计应用的某些部分。

OAuth2 设置

使用 OAuth 2.0 授权对 Google Ads API 服务器的调用时，您应设置以下配置键：

• AuthorizationMethod：设置为 OAuth2。
• OAuth2Mode：设置为 APPLICATION 或 SERVICE_ACCOUNT。
• OAuth2ClientId：将此值设置为您的 OAuth 2.0 客户端 ID。
• OAuth2ClientSecret：将此值设置为您的 OAuth 2.0 客户端密钥。
• OAuth2Scope：如果您想为多个 API 授权 OAuth 2.0 令牌，请将此值设置为不同的范围。此设置为可选设置。
• UseApplicationDefaultCredentials：将此值设置为 true，以使用应用默认凭证进行身份验证（在 Google.Ads.GoogleAds v24.1.0 及更高版本中受支持；config.LoadFromEnvironmentVariables() 会读取不带前缀的 USE_APPLICATION_DEFAULT_CREDENTIALS 环境变量）。
• Credentials：（仅限运行时，在 v27.0.0 及更高版本中受支持）在运行时直接在 GoogleAdsConfig 上注入预构建的 ICredential 或 GoogleCredential 实例。

如果您使用的是 OAuth2Mode == APPLICATION，则需要设置以下额外的配置键：

• OAuth2RefreshToken：如果您想重复使用 OAuth 2.0 令牌，请将此值设置为预先生成的 OAuth 2.0 刷新令牌。此设置为可选设置。
• OAuth2RedirectUri：将此值设置为 OAuth 2.0 重定向网址。此设置是可选的。

如需了解详情，请参阅以下指南：

• OAuth 桌面应用流程
• OAuth Web 应用流程

如果您使用的是 OAuth2Mode == SERVICE_ACCOUNT，则需要设置以下额外的配置键：

• OAuth2SecretsJsonPath：将此值设置为 OAuth 2.0 JSON 密钥文件的路径。
• OAuth2PrnEmail：使用 Google Workspace 全网域委派时，请将此值设置为您要模拟的账号的邮箱。此设置是可选的。

如需了解详情，请参阅 OAuth 服务账号流程指南。

交通设置

• UseGrpcCore：将此设置设为 true，以使用 Grpc.Core 库作为底层传输层。请参阅使用 Grpc.Core 库。

Google Ads API 设置

以下设置特定于 Google Ads API：

• LoginCustomerId：这是要在请求中使用的授权客户的客户 ID，不带连字符 (-)。
• LinkedCustomerId：只有在通过 Google Ads 界面中的“关联的账号”（Google Ads API 中的 AccountLink 资源）获得授权后，更新实体资源的方法才需要此标头。将此值设置为更新指定客户 ID 的资源的数据提供商的客户 ID。设置时应不带连字符 (-)。 详细了解关联的账号。