التهيئة

توفّر مكتبة عملاء 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 لتجنُّب هذا الخطأ.

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

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

• مسار تطبيق سطح المكتب باستخدام OAuth
• مسار تطبيق الويب باستخدام OAuth

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

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

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

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

• UseGrpcCore: اضبط هذا الإعداد على true لاستخدام مكتبة Grpc.Core كأحد طبقات النقل الأساسية. راجِع مقالة استخدام مكتبة Grpc القديمة.

إعدادات Google Ads API

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

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