پیکربندی

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

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

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

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

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

این کتابخانه همچنین گزینه‌های دیگری برای بار کردن تنظیمات پیکربندی از appsettings.json، فایل‌های JSON سفارشی، متغیرهای محیطی، یا App.config ارائه می‌دهد. برای فعال کردن آن‌ها، بسته NuGet Google.Ads.GoogleAds.Extensions را در پروژه‌تان نصب کنید:

dotnet add package Google.Ads.GoogleAds.Extensions

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

از appsettings.json یا settings.json استفاده کنید

در برنامه‌های .NET 8.0 و ASP.NET Core، کلیدهای پیکربندی‌تان را در بخش GoogleAdsApi در appsettings.json (یا settings.json) قرار دهید:

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

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

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

یا می‌توانید فایل appsettings.json یا settings.json را مستقیماً ازطریق مسیر بااستفاده از LoadFromSettingsJson بار کنید:

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

همچنین می‌توانید با فراخوانی config.TryLoadFromEnvironmentFilePath، مسیر را از متغیر محیطی GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) بار کنید.

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

همچنین می‌توانید از نمونه IConfigurationRoot برای بار کردن فایل JSON مسطح بدون بخش GoogleAdsApi سطح بالا استفاده کنید.

ایجاد فایل JSON

فایل JSON با نام GoogleAdsApi.json ایجاد کنید که کلیدهای پیکربندی را در سطح ریشه تعریف می‌کند:

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

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

سپس، فایل JSON را در IConfigurationRoot بار کنید:

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

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

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

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

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

استفاده از App.config

در برنامه‌های .NET Framework، همه تنظیمات مختص 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="" />

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

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

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

فایل 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 (GoogleAdsApi.config) مشخص کرده‌اید ایجاد کنید، و گره پیکربندی GoogleAdsApi را از App.config به این فایل منتقل کنید:

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

  3. قوانین ساخت را در .csproj به‌روز کنید. فایل پیکربندی جدید را در پروژه‌تان اضافه کنید و ویژگی کپی کردن در فهرست راهنمای خروجی آن را روی همیشه کپی شود تنظیم کنید. پروژه‌تان را بازسازی و اجرا کنید تا برنامه‌تان مقادیر را از فایل پیکربندی جدید دریافت کند.

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

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

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 تنظیم کنید. این تنظیم اختیاری است.

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

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

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

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

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

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

تنظیمات Google Ads API

تنظیمات زیر مختص Google Ads API است:

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