التهيئة

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    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"></section>
  </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=""/>

    <!-- 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"></section>
  </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": "",

    "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":
    {
        "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);

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

استخدام مصدر بيانات عام

يمكنك أيضًا تحميل الإعدادات، أو أجزاء منها، من مصدر بيانات عام، بما في ذلك مصدر بيانات مشفّر:

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file.

CryptoStream strm = ....

StreamReader rdr = new StreamReader(strm);
// Configure the OAuth credentials from the encrypted file.
config.LoadOAuth2SecretsFromStream(rdr);

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.

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