الإعدادات

توفِّر مكتبة برامج 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" />
  </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"/>
  </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);

اطّلع على القائمة الكاملة لمتغيرات البيئة المتوافقة.

حقول الإعدادات

في ما يلي قائمة الإعدادات المتاحة في مكتبة .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

عند استخدام 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: اضبط هذه القيمة على مسار ملف إعداد OAuth2 JSON.

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

إعدادات وسائل النقل

  • UseGrpcCore: اضبُط هذا الإعداد على true لاستخدام مكتبة Grpc.Core كطبقة النقل الأساسية. يمكنك الاطّلاع على دليل دعم gRPC لمعرفة المزيد من التفاصيل.

إعدادات Google Ads API

الإعدادات التالية خاصة بواجهة Google Ads API.

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