Yapılandırma

Google Ads API istemci kitaplığı, kitaplık davranışını özelleştirmek için kullanabileceğiniz çeşitli yapılandırma ayarları sunar.

Kitaplığı çalışma zamanında yapılandırma

İstemci kitaplığını yapılandırmanın tercih edilen yolu, çalışma zamanında bir GoogleAdsConfig nesnesi başlatmaktır:

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

GoogleAdsClient client = new GoogleAdsClient(config);

Alternatif yapılandırma seçenekleri

Kitaplık, yapılandırma ayarlarını yüklemek için ek seçenekler de sunar. Bunları etkinleştirmek için projenizdeki Google.Ads.GoogleAds.Extensions paketine bir NuGet referansı ekleyin.

Bu seçeneklerden birini kullanırsanız yapılandırma ayarları otomatik olarak alınmaz. Bunları aşağıdaki bölümlerde gösterildiği gibi açıkça yüklemeniz gerekir. Ayarları harici dosyalardan veya akışlardan yüklerken dosya G/Ç istisnalarını (ör. FileNotFoundException veya UnauthorizedAccessException) işlediğinizden emin olun.

App.config'i kullanma

Google Ads API'ye özgü tüm ayarlar, App.config dosyasının GoogleAdsApi düğümünde saklanır. Tipik bir yapılandırma App.config şu şekildedir:

<?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="" />

    <!-- 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>

Yapılandırma ayarlarını bir App.config dosyasından yüklemek için GoogleAdsConfig nesnesinde LoadFromDefaultAppConfigSection yöntemini çağırın:

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

Ayrı bir App.config dosyası belirtin

App.config dosyanızın karmaşık olmasını istemiyorsanız kitaplığa özel yapılandırmayı configSource özelliğini kullanarak kendi yapılandırma dosyasına taşıyabilirsiniz:

  1. App.config içinde bir configSource belirtin. Harici bir yapılandırma dosyasına referans vermek için App.config dosyanızı değiştirin:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config" />
</configuration>

  2. Yapılandırma dosyanızın içeriğini belirtin. configSource (GoogleAdsApi.config) içinde belirttiğiniz adla başka bir yapılandırma dosyası oluşturun ve GoogleAdsApi yapılandırma düğümünü App.config dosyanızdan bu dosyaya taşıyın:

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

  3. .csproj dosyanızdaki derleme kurallarını güncelleyin. Yeni yapılandırma dosyasını projenize ekleyin ve Copy to Output Directory (Çıkış dizinine kopyala) özelliğini Copy always (Her zaman kopyala) olarak ayarlayın. Uygulamanızın yeni yapılandırma dosyasındaki değerleri alması için projenizi yeniden derleyip çalıştırın.

Özel JSON dosyası kullanma

İstemci kitaplığını yapılandırmak için IConfigurationRoot örneği kullanabilirsiniz.

JSON dosyası oluşturma

App.config dosyasına benzer bir yapıya sahip GoogleAdsApi.json adlı bir JSON dosyası oluşturun:

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

Yapılandırmayı yükleme

Ardından, JSON dosyasını bir IConfigurationRoot içine yükleyin:

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 dosyasını kullanma

Buradaki işlem, özel bir JSON dosyası kullanmaya benzer. Ancak anahtarların GoogleAdsApi adlı bir bölüm adı içinde olması gerekir:

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

Ardından, uygulamanızın IConfiguration örneğinden GoogleAdsApi bölümünü ayıklayın (örneğin, ASP.NET Core tarafından eklenen veya ConfigurationBuilder ile oluşturulan):

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

Alternatif olarak, settings.json dosyasını doğrudan yoldan config.LoadFromSettingsJson(filePath, "GoogleAdsApi") ile veya GOOGLE_ADS_CONFIGURATION_FILE_PATH ortam değişkeninden EnvironmentVariableNames.CONFIG_FILE_PATH config.TryLoadFromEnvironmentFilePath kullanarak yükleyebilirsiniz.

Ortam değişkenlerini kullanma

GoogleAdsClient'i ortam değişkenlerini kullanarak da başlatabilirsiniz:

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

Desteklenen ortam değişkenlerinin tam listesini inceleyin.

Genel bir akış kullanma

Yapılandırmayı veya bir bölümünü şifrelenmiş olanlar da dahil olmak üzere genel bir akıştan da yükleyebilirsiniz:

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

Yapılandırma alanları

Aşağıdaki bölümlerde, Google Ads .NET kitaplığı tarafından desteklenen ayarlar listelenmektedir.

Bağlantı ayarları

  • Timeout: Hizmet zaman aşımını milisaniye cinsinden ayarlamak için bu anahtarı kullanın. Varsayılan değer, googleads_grpc_service_config.json'daki method_config/timeout ayarına göre belirlenir. Bir API çağrısının maksimum süresi için daha kısa bir sınır uygulamanız gerekiyorsa daha düşük bir değer ayarlayın. Zaman aşımını 2 saat veya daha fazla olarak ayarlayabilirsiniz ancak API, çok uzun süren isteklerde zaman aşımına uğrayabilir ve DEADLINE_EXCEEDED hatası döndürebilir.
  • ProxyServer: İnternete bağlanmak için proxy kullanıyorsanız bunu HTTP proxy sunucusu URL'sine ayarlayın.
  • ProxyUser: Bunu, proxy sunucusunda kimlik doğrulaması yapmak için gereken kullanıcı adı olarak ayarlayın. Kullanıcı adı gerekmiyorsa bu alanı boş bırakın.
  • ProxyPassword: ProxyUser için bir değer ayarladıysanız bunu ProxyUser şifresine ayarlayın.
  • ProxyDomain: Proxy sunucunuz için bir alan adı ayarlanması gerekiyorsa bu değeri ProxyUser alan adı olarak ayarlayın.
  • MaxReceiveMessageLengthInBytes: İstemci kitaplığının işleyebileceği API yanıtının maksimum boyutunu artırmak için bu ayarı kullanın. Varsayılan değer 64 MB'tır.
  • MaxMetadataSizeInBytes: İstemci kitaplığının işleyebileceği API hata yanıtının maksimum boyutunu artırmak için bu ayarı kullanın. Varsayılan değer 16 MB'tır.

Belirli ResourceExhausted hatalarını düzeltmek için MaxReceiveMessageLengthInBytes ve MaxMetadataSizeInBytes ayarlarını düzenleyin. Bu ayarlar, aşağıdaki biçimdeki hataları giderir:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

Bu örnekte hata, ileti boyutunun (423184132 bytes) kitaplığın işleyebileceğinden (67108864 bytes) büyük olmasından kaynaklanmaktadır. Bu hatayı önlemek için MaxReceiveMessageLengthInBytes değerini 500000000 olarak artırın. Hatanın, kodunuzun önemli ölçüde büyük bir yanıt nesnesi (ör. büyük bir SearchGoogleAdsResponse) işlediğini de gösterdiğini unutmayın. Bu durum, .NET'in Large Object Heap'i nedeniyle kodunuzun performansını etkileyebilir. Bu durum performansla ilgili bir sorun haline gelirse API çağrılarınızı nasıl yeniden düzenleyeceğinizi veya uygulamanızın bazı bölümlerini nasıl yeniden tasarlayacağınızı araştırmanız gerekebilir.

OAuth2 ayarları

Google Ads API sunucularına karşı yaptığınız çağrıları yetkilendirmek için OAuth 2.0'ı kullanırken aşağıdaki yapılandırma anahtarlarını ayarlamanız gerekir:

  • AuthorizationMethod: OAuth2 olarak ayarlandı.
  • OAuth2Mode: APPLICATION veya SERVICE_ACCOUNT olarak ayarlanır.
  • OAuth2ClientId: Bu değeri OAuth 2.0 istemci kimliğiniz olarak ayarlayın.
  • OAuth2ClientSecret: Bu değeri OAuth 2.0 istemci gizli anahtarınız olarak ayarlayın.
  • OAuth2Scope: Birden fazla API için OAuth 2.0 jetonlarını yetkilendirmek istiyorsanız bu değeri farklı kapsamlara ayarlayın. Bu ayar isteğe bağlıdır.
  • UseApplicationDefaultCredentials: Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak kimlik doğrulamak için bu değeri true olarak ayarlayın (Google.Ads.GoogleAds v24.1.0 ve sonraki sürümlerde desteklenir; config.LoadFromEnvironmentVariables(), önek içermeyen USE_APPLICATION_DEFAULT_CREDENTIALS ortam değişkenini okur).
  • Credentials: (Yalnızca çalışma zamanı, v27.0.0 ve sonraki sürümlerde desteklenir) Önceden oluşturulmuş bir ICredential veya GoogleCredential örneğini çalışma zamanında doğrudan GoogleAdsConfig içine ekleyin.

OAuth2Mode == APPLICATION kullanıyorsanız aşağıdaki ek yapılandırma anahtarlarını ayarlamanız gerekir:

  • OAuth2RefreshToken: OAuth 2.0 jetonlarını yeniden kullanmak istiyorsanız bu değeri önceden oluşturulmuş bir OAuth 2.0 yenileme jetonu olarak ayarlayın. Bu ayar isteğe bağlıdır.
  • OAuth2RedirectUri: Bu değeri OAuth 2.0 yönlendirme URL'si olarak ayarlayın. Bu ayar isteğe bağlıdır.

Daha fazla bilgi için aşağıdaki rehberlere bakın:

OAuth2Mode == SERVICE_ACCOUNT kullanıyorsanız aşağıdaki ek yapılandırma anahtarlarını ayarlamanız gerekir:

  • OAuth2SecretsJsonPath: Bu değeri OAuth 2.0 JSON anahtar dosyasının yoluna ayarlayın.
  • OAuth2PrnEmail: Bu değeri, Google Workspace alan genelinde yetkiyi kullanırken kimliğine büründüğünüz hesabın e-posta adresi olarak ayarlayın. Bu ayar isteğe bağlıdır.

Daha fazla bilgi için OAuth hizmet hesabı akışı kılavuzunu inceleyin.

Ulaşım ayarları

  • UseGrpcCore: Temel taşıma katmanı olarak Grpc.Core kitaplığını kullanmak için bu ayarı true olarak belirleyin. Grpc.Core kitaplığını kullanma başlıklı makaleyi inceleyin.

Google Ads API ayarları

Aşağıdaki ayarlar Google Ads API'ye özeldir:

  • LoginCustomerId: Bu, istekte kullanılacak yetkili müşterinin müşteri kimliğidir. Kısa çizgi içermez (-).
  • LinkedCustomerId: Bu üstbilgi yalnızca, Google Ads kullanıcı arayüzündeki Bağlı Hesaplar (Google Ads API'deki AccountLink kaynağı) üzerinden izin verildiğinde bir öğenin kaynaklarını güncelleyen yöntemler için gereklidir. Bu değeri, belirtilen müşteri kimliğinin kaynaklarını güncelleyen veri sağlayıcının müşteri kimliğine ayarlayın. Bu kimlik, tire olmadan ayarlanmalıdır (-). Bağlı hesaplar hakkında daha fazla bilgi edinin.