التهيئة

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