التهيئة

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

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

حقول الضبط

في ما يلي قائمة بالإعدادات التي تتيحها مكتبة 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. إذا أصبحت هذه المشكلة تؤثر في الأداء، قد تحتاج إلى استكشاف كيفية إعادة تنظيم طلبات البيانات من واجهة برمجة التطبيقات أو إعادة تصميم أجزاء من تطبيقك.

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