الإعدادات

توفّر مكتبة برامج Google Ads API عدة إعدادات ضبط يمكنك استخدامها لتخصيص سلوك المكتبة.

ضبط المكتبة في وقت التشغيل

والطريقة المفضّلة لضبط مكتبة البرامج هي إعداد عنصر GoogleAdsConfig في وقت التشغيل:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "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". 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 لتجنُّب هذا الخطأ.

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