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:

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

Alternatif yapılandırma seçenekleri

Kitaplık ayrıca appsettings.json, özel JSON dosyaları, ortam değişkenleri veya App.config'dan yapılandırma ayarlarını yüklemek için ek seçenekler sunar. Bunları etkinleştirmek için projenize Google.Ads.GoogleAds.Extensions NuGet paketini yükleyin:

dotnet add package Google.Ads.GoogleAds.Extensions

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.

appsettings.json veya settings.json dosyasını kullanma

.NET 8.0 ve ASP.NET Core uygulamalarında, yapılandırma anahtarlarınızı appsettings.json (veya settings.json) dosyasındaki GoogleAdsApi bölümüne yerleştirin:

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "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) ve LoadFromConfigurationSection ile yükleyin:

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

Alternatif olarak, LoadFromSettingsJson kullanarak bir appsettings.json veya settings.json dosyasını doğrudan yola göre yükleyebilirsiniz:

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

Yolu, config.TryLoadFromEnvironmentFilePath yöntemini çağırarak GOOGLE_ADS_CONFIGURATION_FILE_PATH ortam değişkeninden (EnvironmentVariableNames.CONFIG_FILE_PATH) de yükleyebilirsiniz.

Özel JSON dosyası kullanma

Üst düzey GoogleAdsApi bölümü olmayan düz bir JSON dosyasını yüklemek için IConfigurationRoot örneğini de kullanabilirsiniz.

JSON dosyası oluşturma

Kök düzeyinde yapılandırma anahtarlarını tanımlayan GoogleAdsApi.json adlı bir JSON dosyası oluşturun:

{
  "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"
}

Yapılandırmayı yükleme

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

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

Ortam değişkenlerini kullanma

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

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

Not: GoogleAdsConfig.OAuth2Mode varsayılan olarak APPLICATION değerine ayarlandığından, GOOGLE_ADS_JSON_KEY_FILE_PATH kullanarak bir hizmet hesabıyla kimlik doğrulaması yaparken GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT değerini de ayarladığınızdan emin olun.

Desteklenen ortam değişkenlerinin tam listesini inceleyin.

App.config'i kullanma

.NET Framework uygulamalarında, Google Ads API'ye özgü tüm ayarlar App.config dosyasının GoogleAdsApi düğümünde depolanır. Standart 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="" />

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

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

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

Ayrı bir App.config yapılandırma dosyası belirtme

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 Çıkış Dizinine Kopyala özelliğini 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.

Genel bir akış kullanma

Yapılandırmayı veya yapılandırmanın bazı bölümlerini, şifrelenmiş bir akış da dahil olmak üzere genel bir akıştan 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 listelenmiştir.

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'deki 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 uzun bir süreye ayarlayabilirsiniz ancak API, son derece 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 sunucu URL'si olarak ayarlayın.
• ProxyUser: Bu değeri, proxy sunucusunda kimlik doğrulaması yapmak için gereken kullanıcı adına 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) daha büyük olmasından kaynaklanıyor. Bu hatayı önlemek için MaxReceiveMessageLengthInBytes değerini 500000000 olarak artırın. Hata, kodunuzun önemli ölçüde büyük bir yanıt nesnesini (ör. büyük bir SearchGoogleAdsResponse) işlediğini de gösterir. Bu durum, .NET'in Büyük Nesne Yığını 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 yönelik çağrılarınızı 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ğrulaması yapmak için bu değeri true olarak ayarlayın (Google.Ads.GoogleAds v24.1.0 ve sonraki sürümlerde desteklenir; config.LoadFromEnvironmentVariables(), ön eki olmayan 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 kılavuzları inceleyin:

• OAuth masaüstü uygulaması akışı
• OAuth web uygulaması akışı

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. Kimlik, kısa çizgi (-) olmadan ayarlanmalıdır. Bağlı hesaplar hakkında daha fazla bilgi edinin.