التهيئة

توفّر مكتبة عملاء 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);

يمكنك أيضًا تحميل المسار من متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) من خلال استدعاء config.TryLoadFromEnvironmentFilePath.

استخدام ملف 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);

ملاحظة: بما أنّ GoogleAdsConfig.OAuth2Mode يتم ضبطه تلقائيًا على APPLICATION، عند المصادقة باستخدام حساب خدمة من خلال GOOGLE_ADS_JSON_KEY_FILE_PATH، يجب التأكّد أيضًا من ضبط GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT.

القائمة الكاملة لمتغيرات البيئة المتوافقة

استخدام ملف 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 مزدحمًا، يمكنك نقل الإعدادات الخاصة بالمكتبة إلى ملف الإعدادات الخاص بها باستخدام السمة 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. أدرِج ملف الإعداد الجديد في مشروعك واضبط السمة Copy to Output Directory (النسخ إلى دليل الإخراج) على Copy always (النسخ دائمًا). أعِد إنشاء مشروعك وتشغيله لكي يحصل تطبيقك على القيم من ملف الإعداد الجديد.

استخدام مصدر بيانات عام

يمكنك أيضًا تحميل الإعدادات أو أجزاء منها من مصدر بيانات عام، بما في ذلك مصدر بيانات مشفّر:

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

حقول الإعداد

تسرد الأقسام التالية الإعدادات المتوافقة مع مكتبة ‎ .NET في "إعلانات Google".

إعدادات إمكانية الاتصال

• ‫Timeout: استخدِم هذا المفتاح لضبط مهلة الخدمة بالملي ثانية. يتم ضبط القيمة التلقائية استنادًا إلى إعداد method_config/timeout في googleads_grpc_service_config.json. اضبط قيمة أقل إذا كنت بحاجة إلى فرض حدّ أقصر على الحدّ الأقصى للوقت المخصّص لطلب بيانات من واجهة برمجة التطبيقات. يمكنك ضبط المهلة على ساعتَين أو أكثر، ولكن قد تنتهي مهلة الطلبات الطويلة جدًا في واجهة برمجة التطبيقات، ما يؤدي إلى ظهور الخطأ DEADLINE_EXCEEDED.
• ‫ProxyServer: اضبط هذا الإعداد على عنوان URL الخاص بخادم وكيل HTTP إذا كنت تستخدم خادمًا وكيلاً للاتصال بالإنترنت.
• ‫ProxyUser: اضبط هذا الإعداد على اسم المستخدم المطلوب للمصادقة مع الخادم الوكيل. اترك هذا الحقل فارغًا إذا لم يكن اسم المستخدم مطلوبًا.
• ‫ProxyPassword: اضبط هذه السمة على كلمة مرور ProxyUser إذا ضبطت قيمة لـ ProxyUser.
• ‫ProxyDomain: اضبط هذه السياسة على نطاق ProxyUser إذا كان الخادم الوكيل يتطلّب ضبط نطاق.
• ‫MaxReceiveMessageLengthInBytes: استخدِم هذا الإعداد لزيادة الحد الأقصى لحجم الردّ من واجهة برمجة التطبيقات الذي يمكن لمكتبة البرامج التعامل معه. القيمة التلقائية هي 64 ميغابايت.
• MaxMetadataSizeInBytes: استخدِم هذا الإعداد لزيادة الحد الأقصى لحجم استجابة الخطأ في واجهة برمجة التطبيقات التي يمكن لمكتبة العميل معالجتها. القيمة التلقائية هي 16 ميغابايت.

اضبط إعدادات MaxReceiveMessageLengthInBytes وMaxMetadataSizeInBytes لإصلاح بعض أخطاء ResourceExhausted. تعالج هذه الإعدادات الأخطاء في النموذج:

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: اضبط هذه القيمة على نطاقات مختلفة إذا أردت تفويض رموز 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: اضبط هذه القيمة على عنوان URL لإعادة التوجيه في OAuth 2.0. هذا الإعداد اختياري.

لمزيد من التفاصيل، يُرجى الاطّلاع على الأدلة التالية:

• مسار تطبيق OAuth المتوافق مع أجهزة الكمبيوتر المكتبي
• مسار تطبيق الويب OAuth

إذا كنت تستخدم 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" (مورد AccountLink في Google Ads API). اضبط هذه القيمة على رقم تعريف العميل لمزوِّد البيانات الذي يعدّل موارد رقم تعريف العميل المحدّد. يجب ضبطه بدون واصلات (-). مزيد من المعلومات حول الحسابات المرتبطة