التهيئة

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

الخطوة 1: تحديد 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>

الخطوة 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. اضبُط قيمة أقل إذا كنت بحاجة إلى فرض حدّ أقصر على الحد الأقصى لوقت طلب البيانات من واجهة برمجة التطبيقات. يمكنك ضبط المهلة على ساعتَين أو أكثر، ولكن قد تنتهي مهلة واجهة برمجة التطبيقات لطلبات البيانات التي تستغرق وقتًا طويلاً جدًا وتعرض خطأ 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 لتجنُّب هذا الخطأ.

يُرجى العِلم أنّ الخطأ يشير أيضًا إلى أنّ الرمز البرمجي قد عالج عنصر `Response` كبيرًا جدًا (مثل `SearchGoogleAdsResponse` كبير). قد يؤثر ذلك في أداء الرمز البرمجي بسبب Large Object Heap في ‎ .NET.SearchGoogleAdsResponse إذا أصبح ذلك مصدر قلق بشأن الأداء، قد تحتاج إلى استكشاف كيفية إعادة تنظيم طلبات البيانات من واجهة برمجة التطبيقات أو إعادة تصميم أجزاء من تطبيقك.

إعدادات OAuth2

عند استخدام OAuth2 لتفويض طلباتك من خوادم Google Ads API، عليك ضبط مفاتيح الإعداد التالية:

  • AuthorizationMethod: اضبُط هذا الخيار على OAuth2.
  • OAuth2Mode: اضبُط هذا الخيار على APPLICATION أو SERVICE_ACCOUNT.
  • OAuth2ClientId: اضبُط هذا الخيار على معرّف عميل OAuth2.
  • OAuth2ClientSecret: اضبُط هذا الخيار على سرّ عميل OAuth2.
  • OAuth2Scope: اضبُط هذا الخيار على نطاقات مختلفة إذا كنت تريد تفويض رموز OAuth2 المميزة لعدة واجهات برمجة تطبيقات. هذا الإعداد اختياري.

إذا كنت تستخدم OAuth2Mode == APPLICATION، عليك ضبط مفاتيح الإعداد الإضافية التالية.

  • OAuth2RefreshToken: اضبُط هذه القيمة على الرمز المميز لإعادة تحميل OAuth2 الذي تم إنشاؤه مسبقًا إذا كنت تريد إعادة استخدام الرموز المميزة لـ OAuth2. هذا الإعداد اختياري.
  • OAuth2RedirectUri: اضبُط هذا الخيار على عنوان URL لإعادة التوجيه في OAuth2. هذا الإعداد اختياري.

اطّلِع على الأدلة التالية لمزيد من التفاصيل:

إذا كنت تستخدم OAuth2Mode == SERVICE_ACCOUNT، عليك ضبط مفاتيح الإعداد الإضافية التالية.

  • OAuth2PrnEmail: اضبُط هذا الخيار على عنوان البريد الإلكتروني للحساب الذي تنتحله.
  • OAuth2SecretsJsonPath: اضبُط هذا الخيار على مسار ملف إعداد JSON في OAuth2.

اطّلِع على دليل مسار حساب خدمة OAuth لمزيد من التفاصيل.

إعدادات النقل

إعدادات Google Ads API

الإعدادات التالية خاصة بـ Google Ads API.

  • DeveloperToken: اضبُط هذا الخيار على الرمز المميّز للمطوّر.
  • LoginCustomerId: هذا هو رقم تعريف العميل المفوّض الذي سيتم استخدامه في الطلب، بدون شُرط (-).
  • LinkedCustomerId: لا يكون هذا العنوان مطلوبًا إلا للطُرق التي تعدِّل موارد كيان عندما يتم منح الإذن من خلال "الحسابات المرتبطة" في واجهة مستخدم "إعلانات Google" (مورد AccountLink في Google Ads API). اضبُط هذا الخيار على رقم تعريف العميل لمزوّد البيانات الذي يعدِّل موارد رقم تعريف العميل المحدّد. يجب ضبطه بدون شُرط (-). مزيد من المعلومات عن "الحسابات المرتبطة".