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