پیکربندی

کتابخانه کارخواه Google Ads API چندین تنظیم پیکربندی ارائه می‌دهد که می‌توانید از آن‌ها برای سفارشی‌سازی رفتار کتابخانه استفاده کنید.

پیکربندی کتابخانه در زمان اجرا

روش ترجیحی برای پیکربندی کتابخانه کارخواه، مقداردهی اولیه شیء GoogleAdsConfig در زمان اجرا است:

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

گزینه‌های پیکربندی جایگزین

این کتابخانه همچنین گزینه‌های اضافی برای بار کردن تنظیمات پیکربندی ارائه می‌دهد. برای فعال کردن آن‌ها، مرجع NuGet را به Google.Ads.GoogleAds.Extensions بسته در پروژه‌تان اضافه کنید.

اگر از یکی از این گزینه‌ها استفاده کنید، تنظیمات پیکربندی به‌طور خودکار انتخاب نمی‌شود؛ باید آن‌ها را به‌طور صریح بار کنید، همان‌طور که در بخش‌های زیر نشان داده شده است. هنگام بار کردن تنظیمات از فایل‌ها یا جاری‌سازی‌های خارجی، حتماً استثناهای ورودی/خروجی فایل (مثل FileNotFoundException یا UnauthorizedAccessException) را مدیریت کنید.

استفاده از 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="" />

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

برای بار کردن تنظیمات پیکربندی از فایل App.config، روش LoadFromDefaultAppConfigSection را در شیء GoogleAdsConfig فراخوانی کنید:

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 (GoogleAdsApi.config) مشخص کرده‌اید ایجاد کنید، و گره پیکربندی GoogleAdsApi را از 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": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

بار کردن پیکربندی

سپس، فایل 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": {
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

سپس، بخش GoogleAdsApi را از نمونه IConfiguration برنامه‌تان استخراج کنید (برای نمونه، تزریق‌شده توسط ASP.NET Core یا ساخته‌شده با ConfigurationBuilder):

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

یا می‌توانید فایل settings.json را مستقیماً ازطریق مسیر با config.LoadFromSettingsJson(filePath, "GoogleAdsApi") یا از متغیر محیطی GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) بااستفاده از config.TryLoadFromEnvironmentFilePath بار کنید.

استفاده از متغیرهای محیط

همچنین می‌توانید GoogleAdsClient را بااستفاده از متغیرهای محیطی مقداردهی اولیه کنید:

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

توجه: چون GoogleAdsConfig.OAuth2Mode به‌طور پیش‌فرض روی APPLICATION تنظیم شده است، هنگام اصالت‌سنجی با حساب سرویس بااستفاده از GOOGLE_ADS_JSON_KEY_FILE_PATH، حتماً GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT را هم تنظیم کنید.

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

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

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

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

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

بخش‌های زیر تنظیمات پشتیبانی‌شده توسط کتابخانه 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: از این تنظیم برای افزایش حداکثر اندازه پاسخ میانای برنامه‌سازی کاربردی که کتابخانه کارخواه می‌تواند مدیریت کند استفاده کنید. مقدار پیش‌فرض ۶۴ مگابایت است.
• MaxMetadataSizeInBytes: از این تنظیم برای افزایش حداکثر اندازه پاسخ خطای میانای برنامه‌سازی کاربردی که کتابخانه کارخواه می‌تواند مدیریت کند استفاده کنید. مقدار پیش‌فرض ۱۶ مگابایت است.

برای برطرف کردن برخی‌از خطاهای ResourceExhausted، تنظیمات MaxReceiveMessageLengthInBytes و MaxMetadataSizeInBytes را اصلاح کنید. این تنظیمات به خطاهای فرم می‌پردازد:

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

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

تنظیمات OAuth2

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

• AuthorizationMethod: روی OAuth2 تنظیم شد.
• ‫OAuth2Mode: روی APPLICATION یا SERVICE_ACCOUNT تنظیم کنید.
• ‫OAuth2ClientId: این مقدار را روی شناسه کارخواه OAuth 2.0 تنظیم کنید.
• OAuth2ClientSecret: این مقدار را روی رمز کارخواه OAuth 2.0 خود تنظیم کنید.
• OAuth2Scope: اگر می‌خواهید برای چندین API، توکن‌های OAuth 2.0 را مجاز کنید، این مقدار را روی دامنه‌های مختلف تنظیم کنید. این تنظیم اختیاری است.
• UseApplicationDefaultCredentials: این مقدار را روی true تنظیم کنید تا بااستفاده از «اطلاعات اعتباری پیش‌فرض برنامه» اصالت‌سنجی کنید (در Google.Ads.GoogleAds v24.1.0 و نسخه‌های جدیدتر پشتیبانی می‌شود؛ config.LoadFromEnvironmentVariables() متغیر محیطی USE_APPLICATION_DEFAULT_CREDENTIALS بدون پیشوند را می‌خواند).
• Credentials: (فقط زمان اجرا، در v27.0.0 و نسخه‌های جدیدتر پشتیبانی می‌شود) تزریق یک نمونه ICredential یا GoogleCredential ازپیش ساخته‌شده مستقیماً در GoogleAdsConfig در زمان اجرا.

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

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

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

• جریان برنامه رایانه‌ای OAuth
• جریان برنامه وب OAuth

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

• ‫OAuth2SecretsJsonPath: این مقدار را روی مسیر فایل کلید JSON مربوط به OAuth 2.0 تنظیم کنید.
• OAuth2PrnEmail: این مقدار را روی نشانی ایمیل حسابی تنظیم کنید که هنگام استفاده از واگذاری در سطح دامنه Google Workspace، خود را به‌جای آن جا می‌زنید. این تنظیم اختیاری است.

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

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

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

تنظیمات Google Ads API

تنظیمات زیر مختص «میانای برنامه‌سازی کاربردی Google Ads» است:

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