پیکربندی

کتابخانه کلاینت 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"></section>
  </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 به فایل پیکربندی جداگانه‌ای منتقل کنید.

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

App.config خود را به صورت زیر تغییر دهید:

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

مرحله ۲: محتویات فایل پیکربندی خود را مشخص کنید

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

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

مرحله ۳: قوانین ساخت را در csproj خود اصلاح کنید

در نهایت، فایل پیکربندی جدید را به پروژه خود اضافه کنید. ویژگی‌های این فایل را به Always copy to output folder تغییر دهید.

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

استفاده از یک فایل 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 : اگر از پروکسی برای اتصال به اینترنت استفاده می‌کنید، این گزینه را روی آدرس اینترنتی سرور پروکسی HTTP تنظیم کنید.
  • ProxyUser : این را روی نام کاربری مورد نیاز برای احراز هویت در برابر سرور پروکسی تنظیم کنید. اگر نام کاربری لازم نیست، این قسمت را خالی بگذارید.
  • ProxyPassword : اگر برای ProxyUser مقداری تعیین کرده‌اید، این را روی رمز عبور ProxyUser تنظیم کنید.
  • ProxyDomain : اگر سرور پروکسی شما نیاز به تنظیم دامنه برای ProxyUser دارد، این را روی آن تنظیم کنید.
  • MaxReceiveMessageLengthInBytes : از این تنظیم برای افزایش حداکثر اندازه پاسخ API که کتابخانه کلاینت می‌تواند مدیریت کند، استفاده کنید. مقدار پیش‌فرض ۶۴ مگابایت است.
  • MaxMetadataSizeInBytes : از این تنظیم برای افزایش حداکثر اندازه پاسخ خطای API که کتابخانه کلاینت می‌تواند مدیریت کند، استفاده کنید. مقدار پیش‌فرض ۱۶ مگابایت است.

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

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

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

تنظیمات OAuth2

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

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

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

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

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

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

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

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

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

  • UseGrpcCore : برای استفاده از کتابخانه Grpc.Core به عنوان لایه انتقال زیرین، این تنظیم را روی true تنظیم کنید. به بخش Use the legacy Grpc library مراجعه کنید.

تنظیمات API گوگل ادز

تنظیمات زیر مختص API تبلیغات گوگل هستند.

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