設定

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 中的建構規則。在專案中加入新的設定檔，並將其「Copy to Output Directory」屬性設為「Copy always」。重新建構並執行專案，讓應用程式從新的設定檔中擷取值。

使用一般串流

您也可以從一般串流 (包括加密串流) 載入設定或部分設定：

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：如果您使用 Proxy 連線至網際網路，請將此項設為 HTTP Proxy 伺服器網址。
• ProxyUser：請將這項設定設為驗證 Proxy 伺服器所需的使用者名稱。如果不需要使用者名稱，請留空。
• ProxyPassword：如果您為 ProxyUser 設定了值，請將此值設為 ProxyUser 的密碼。
• ProxyDomain：如果 Proxy 伺服器需要設定網域，請將此項設為 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 以上版本支援) 在執行階段直接將預先建構的 ICredential 或 GoogleCredential 執行個體插入 GoogleAdsConfig。

如果您使用 OAuth2Mode == APPLICATION，則需要設定下列額外設定金鑰：

• OAuth2RefreshToken：如要重複使用 OAuth 2.0 權杖，請將這個值設為預先產生的 OAuth 2.0 更新權杖。這項設定為選用項目。
• OAuth2RedirectUri：將這個值設為 OAuth 2.0 重新導向網址。這項設定為選用項目。

詳情請參閱下列指南：

• OAuth 桌面應用程式流程
• OAuth 網頁應用程式流程

如果您使用 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 UI 中的「已連結帳戶」(Google Ads API 中的 AccountLink 資源) 取得權限，並更新實體資源的方法時，才需要這個標頭。將這個值設為資料供應商的客戶 ID，該供應商會更新指定客戶 ID 的資源。設定時請勿使用連字號 (-)。 進一步瞭解已連結帳戶。