Google Ads API 用戶端程式庫提供多項配置設定,可用來自訂程式庫行為。
在執行階段設定程式庫
如要設定用戶端程式庫,建議做法是在執行階段初始化 GoogleAdsConfig
物件:
GoogleAdsConfig config = new GoogleAdsConfig()
{
DeveloperToken = "******",
OAuth2Mode = OAuth2Flow.APPLICATION,
OAuth2ClientId = "******.apps.googleusercontent.com",
OAuth2ClientSecret = "******",
OAuth2RefreshToken = "******"
};
GoogleAdsClient client = new GoogleAdsClient(config);
其他設定選項
我們還提供了一些其他設定用戶端程式庫的選項:如要啟用這項功能,請將 Nuget 參照新增至專案的 Google.Ads.GoogleAds.Extensions
套件。
如果您使用其中一個選項,則不會自動選取配置設定,您應按照以下所示方式明確載入配置設定。
使用 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 中的建構規則
最後,在專案中加入新的設定檔。將此檔案的屬性變更為「Always copy 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。
調整
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 UI 中的「已連結帳戶」(Google Ads API 中的AccountLink
資源) 取得權限時,更新實體資源的方法才需要這個標頭。將這個值設為資料供應商的客戶 ID,該供應商的資料會更新指定客戶 ID 的資源。應設定不含連字號 (-
)。進一步瞭解已連結帳戶。