الإعداد

توفّر مكتبة برنامج "إعلانات Google 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: إصلاح قواعد الإصدار في csxlsx

وأخيرًا، أدرِج ملف إعداد جديدًا في مشروعك. غيّر خصائص هذا الملف إلى نسخ النص إلى مجلد الإخراج دائمًا.

يمكنك الآن إنشاء مشروعك وإدارته. سيبدأ تطبيقك في استلام القيم من ملف الإعداد الجديد.

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