設定

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 中的建構規則

最後,在專案中納入新的設定檔。將這個檔案的屬性變更為「Alwayscopy to output folder」(一律複製到輸出資料夾)

現在請建構並執行專案。應用程式會開始從新的設定檔擷取值。

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

請參閱支援環境變數的完整清單

設定欄位

以下列出 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。

調整 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 UI 中的連結資源 (Google Ads API 中的 AccountLink 資源) 時,必須更新實體資源。將這個值設為資料供應商的客戶 ID;這些客戶會更新指定客戶 ID 的資源。設定應不含連字號 (-)。進一步瞭解已連結帳戶