الإعداد

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

التهيئة باستخدام 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 منفصل

إذا كنت لا تريد أن تشوش 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(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(section);
GoogleAdsClient client = new GoogleAdsClient(config);

إعداد المكتبة في وقت التشغيل

ويمكنك أيضًا إعداد GoogleAdsClient في وقت التشغيل.

مثال 1: تهيئة التهيئة في وقت التشغيل

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "APPLICATION",
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******"
};

GoogleAdsClient client = new GoogleAdsClient(config);

المثال 2: التحميل من App.config، مع إلغاء إعداد

GoogleAdsClient client = new GoogleAdsClient(config);
client.Config.DeveloperToken = "******";

التهيئة باستخدام متغيرات البيئة

يمكنك أيضًا إعداد 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). ويمكن أن يكون لذلك تأثيرات على أداء الشفرة بسبب كومة العناصر الكبيرة .NET. إذا أصبح هذا مصدر قلق بشأن الأداء، فقد يتعين عليك استكشاف كيفية إعادة تنظيم طلبات البيانات من واجهة برمجة التطبيقات أو إعادة تصميم أجزاء من تطبيقك.

إعدادات OAuth2

عند استخدام OAuth2 لتفويض المكالمات من خلال خوادم إعلانات Google 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: اضبط هذه القيمة على مسار ملف ضبط JSON2 JSON.

اطلع على دليل تدفق حساب خدمة OAuth للحصول على مزيد من التفاصيل.

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

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

إعدادات إعلانات Google API

الإعدادات التالية تخص إعلانات Google API تحديدًا.

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