التهيئة

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

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  DeveloperToken = "******",
  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. هذا الإعداد اختياري.

يُرجى الاطّلاع على الأدلة التالية لمعرفة مزيد من التفاصيل:

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