پیکربندی

کتابخانه سرویس گیرنده 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 در گره GoogleAdsApi فایل App.config ذخیره می شود. یک پیکربندی معمولی 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 ، روش LoadFromDefaultAppConfigSection را در یک شی GoogleAdsConfig فراخوانی کنید:

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

یک فایل App.config جداگانه مشخص کنید

اگر نمی‌خواهید App.config خود را به هم ریخته کنید، می‌توانید با استفاده از ویژگی configSource پیکربندی مخصوص کتابخانه را به فایل پیکربندی خودش منتقل کنید.

مرحله 1: یک configSource را در App.config خود مشخص کنید

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 خود اصلاح کنید

در نهایت، فایل پیکربندی جدید را در پروژه خود قرار دهید. ویژگی های این فایل را به همیشه در پوشه خروجی کپی کنید .

اکنون پروژه خود را بسازید و اجرا کنید. برنامه شما شروع به دریافت مقادیر از فایل پیکربندی جدید می کند.

از یک فایل JSON سفارشی استفاده کنید

می توانید از یک نمونه IConfigurationRoot برای پیکربندی کتابخانه مشتری استفاده کنید.

یک فایل JSON ایجاد کنید

یک فایل JSON با نام GoogleAdsApi.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);

لیست کامل متغیرهای محیطی پشتیبانی شده را ببینید.

از یک جریان عمومی استفاده کنید

همچنین می‌توانید پیکربندی یا بخش‌هایی از آن را از یک جریان عمومی، از جمله یک جریان رمزگذاری‌شده، بارگیری کنید: 

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  DeveloperToken = "******",
  OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file.

CryptoStream strm = ....

StreamReader rdr = new StreamReader(strm);
// Configure the OAuth credentials from the encrypted file.
config.LoadOAuth2SecretsFromStream(rdr);

GoogleAdsClient client = new GoogleAdsClient(config);

فیلدهای پیکربندی

در زیر لیستی از تنظیمات پشتیبانی شده توسط کتابخانه Google Ads .NET آمده است.

تنظیمات اتصال

  • Timeout : از این کلید برای تنظیم مهلت زمانی سرویس بر حسب میلی ثانیه استفاده کنید. مقدار پیش‌فرض بر اساس تنظیم method_config/timeout در googleads_grpc_service_config.json تنظیم می‌شود. اگر می‌خواهید محدودیت کوتاه‌تری برای حداکثر زمان تماس API اعمال کنید، مقدار کمتری تنظیم کنید. می‌توانید زمان‌بندی را روی ۲ ساعت یا بیشتر تنظیم کنید، اما API ممکن است همچنان درخواست‌های طولانی‌مدت را به پایان برساند و خطای DEADLINE_EXCEEDED را برگرداند.
  • ProxyServer : اگر از پروکسی برای اتصال به اینترنت استفاده می کنید، این را روی URL سرور پروکسی HTTP تنظیم کنید.
  • ProxyUser : این را روی نام کاربری که برای احراز هویت در برابر سرور پراکسی نیاز دارید، تنظیم کنید. اگر نام کاربری لازم نیست این را خالی بگذارید.
  • ProxyPassword : اگر مقداری را برای ProxyUser تعیین کرده اید، آن را روی رمز عبور ProxyUser تنظیم کنید.
  • ProxyDomain : اگر سرور پروکسی شما نیاز به تنظیم دارد، آن را روی دامنه ProxyUser تنظیم کنید.
  • MaxReceiveMessageLengthInBytes : از این تنظیم برای افزایش حداکثر اندازه پاسخ API که کتابخانه سرویس گیرنده می تواند استفاده کند، استفاده کنید. مقدار پیش فرض 64 مگابایت است.
  • MaxMetadataSizeInBytes : از این تنظیم برای افزایش حداکثر اندازه پاسخ خطای API که کتابخانه سرویس گیرنده می تواند استفاده کند، استفاده کنید. مقدار پیش فرض 16 مگابایت است.

تنظیمات MaxReceiveMessageLengthInBytes و MaxMetadataSizeInBytes را برای رفع برخی از خطاهای ResourceExhausted تنظیم کنید. این تنظیمات خطاهای فرم Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)" را نشان می دهد.

در این مثال، خطا به دلیل بزرگتر بودن اندازه پیام ( 423184132 bytes ) از آنچه کتابخانه می تواند مدیریت کند ( 67108864 bytes ) است. برای جلوگیری از این خطا MaxReceiveMessageLengthInBytes به 500000000 افزایش دهید.

توجه داشته باشید که این خطا همچنین نشان می‌دهد که کد شما یک شی Response بسیار بزرگ را مدیریت می‌کند (مانند یک SearchGoogleAdsResponse بزرگ). این می تواند پیامدهای عملکردی برای کد شما به دلیل وجود هیپ شی بزرگ دات نت داشته باشد. اگر این به یک نگرانی عملکرد تبدیل شود، ممکن است مجبور شوید نحوه سازماندهی مجدد تماس های API یا طراحی مجدد بخش هایی از برنامه خود را بررسی کنید.

تنظیمات OAuth2

هنگام استفاده از OAuth2 برای مجاز کردن تماس‌های خود در برابر سرورهای Google Ads API، باید کلیدهای پیکربندی زیر را تنظیم کنید:

  • AuthorizationMethod : روی OAuth2 تنظیم کنید.
  • OAuth2Mode : روی APPLICATION یا SERVICE_ACCOUNT تنظیم کنید.
  • OAuth2ClientId : این مقدار را روی شناسه مشتری OAuth2 خود تنظیم کنید.
  • OAuth2ClientSecret : این مقدار را روی رمز سرویس گیرنده OAuth2 خود تنظیم کنید.
  • OAuth2Scope : اگر می‌خواهید توکن‌های OAuth2 را برای چندین API مجاز کنید، این مقدار را روی دامنه‌های مختلف تنظیم کنید. این تنظیم اختیاری است.

اگر از OAuth2Mode == APPLICATION استفاده می کنید، باید کلیدهای پیکربندی اضافی زیر را تنظیم کنید.

  • OAuth2RefreshToken : اگر می‌خواهید از نشانه‌های OAuth2 مجدداً استفاده کنید، این مقدار را روی یک نشانه تازه‌سازی OAuth2 از پیش تولید شده تنظیم کنید. این تنظیم اختیاری است.
  • OAuth2RedirectUri : این مقدار را روی URL تغییر مسیر OAuth2 تنظیم کنید. این تنظیم اختیاری است.

برای جزئیات بیشتر به راهنمای زیر مراجعه کنید:

اگر از OAuth2Mode == SERVICE_ACCOUNT استفاده می کنید، باید کلیدهای پیکربندی اضافی زیر را تنظیم کنید.

  • OAuth2PrnEmail : این مقدار را روی آدرس ایمیل حسابی که جعل هویت می کنید، تنظیم کنید.
  • OAuth2SecretsJsonPath : این مقدار را روی مسیر فایل پیکربندی OAuth2 JSON قرار دهید.

برای جزئیات بیشتر به راهنمای جریان حساب سرویس OAuth مراجعه کنید.

تنظیمات حمل و نقل

تنظیمات API Google Ads

تنظیمات زیر مختص Google Ads API هستند.

  • DeveloperToken : این را روی توکن توسعه دهنده خود تنظیم کنید.
  • LoginCustomerId : این شناسه مشتری مشتری مجاز برای استفاده در درخواست، بدون خط تیره ( - ) است.
  • LinkedCustomerId : این سرصفحه فقط برای روش‌هایی لازم است که منابع یک نهاد را در صورت مجوز از طریق حساب‌های پیوندی در رابط کاربری Google Ads (منبع AccountLink در Google Ads API) به‌روزرسانی می‌کنند. این مقدار را روی شناسه مشتری ارائه دهنده داده تنظیم کنید که منابع شناسه مشتری مشخص شده را به روز می کند. باید بدون خط تیره ( - ) تنظیم شود. درباره حساب های پیوندی بیشتر بیاموزید .