التهيئة

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN"
};

GoogleAdsClient client = new GoogleAdsClient(config);

خيارات الإعداد البديلة

توفّر المكتبة أيضًا خيارات إضافية لتحميل إعدادات الضبط. لتفعيلها، أضِف مرجع NuGet إلى حزمة Google.Ads.GoogleAds.Extensions في مشروعك.

في حال استخدام أحد الخيارَين، لن يتم استرداد إعدادات الضبط تلقائيًا، بل عليك تحميلها بشكل صريح كما هو موضّح في الأقسام التالية. احرص على التعامل مع استثناءات إدخال/إخراج الملفات (مثل FileNotFoundException أو UnauthorizedAccessException) عند تحميل الإعدادات من الملفات أو عمليات البث الخارجية.

استخدام ملف 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="" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.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 (GoogleAdsApi.config)، وانقل عقدة إعداد GoogleAdsApi من App.config إلى هذا الملف:

    <?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  <!-- More settings. -->
</GoogleAdsApi>

  3. عدِّل قواعد الإنشاء في .csproj. أدرِج ملف الإعداد الجديد في مشروعك واضبط قيمة السمة النسخ إلى دليل الإخراج (Copy to Output Directory) على النسخ دائمًا (Copy always). أعِد إنشاء مشروعك وشغِّله حتى يتمكّن تطبيقك من استرداد القيم من ملف الإعداد الجديد.

استخدام ملف JSON مخصّص

يمكنك استخدام مثيل IConfigurationRoot لإعداد مكتبة البرامج.

إنشاء ملف JSON

أنشِئ ملف JSON باسم GoogleAdsApi.json يتضمّن بنية مشابهة لبنية الملف App.config:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

تحميل الإعدادات

بعد ذلك، حمِّل ملف 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": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

بعد ذلك، استخرِج القسم GoogleAdsApi من مثيل IConfiguration لتطبيقك (على سبيل المثال، تم إدخاله بواسطة ASP.NET Core أو تم إنشاؤه باستخدام ConfigurationBuilder):

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

يمكنك بدلاً من ذلك تحميل ملف settings.json مباشرةً من خلال المسار باستخدام config.LoadFromSettingsJson(filePath, "GoogleAdsApi")، أو من متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) باستخدام config.TryLoadFromEnvironmentFilePath.

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

يمكنك أيضًا تهيئة 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 and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    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 لتجنُّب هذا الخطأ. يُرجى العِلم أنّ الخطأ يشير أيضًا إلى أنّ الرمز البرمجي الخاص بك تعامل مع عنصر استجابة كبير جدًا (مثل SearchGoogleAdsResponse كبير). وقد يكون لذلك آثار على أداء الرمز البرمجي بسبب Large Object Heap في ‎ .NET. إذا أصبح ذلك مصدر قلق بشأن الأداء، قد تحتاج إلى استكشاف كيفية إعادة تنظيم طلبات البيانات من واجهة برمجة التطبيقات أو إعادة تصميم أجزاء من تطبيقك.

إعدادات OAuth2

عند استخدام OAuth 2.0 للموافقة على طلباتك من خوادم Google Ads API، عليك ضبط مفاتيح الإعداد التالية:

  • ‫AuthorizationMethod: اضبط القيمة على OAuth2.
  • ‫OAuth2Mode: اضبط القيمة على APPLICATION أو SERVICE_ACCOUNT.
  • OAuth2ClientId: اضبط هذه القيمة على معرّف عميل OAuth 2.0.
  • استبدِل OAuth2ClientSecret بسر عميل OAuth 2.0.
  • OAuth2Scope: اضبط هذه القيمة على نطاقات مختلفة إذا كنت تريد تفويض رموز OAuth 2.0 المميزة لعدة واجهات برمجة تطبيقات. هذا الإعداد اختياري.
  • UseApplicationDefaultCredentials: اضبط هذه القيمة على true للمصادقة باستخدام "بيانات الاعتماد التلقائية للتطبيق" (المتاحة في Google.Ads.GoogleAds v24.1.0 والإصدارات الأحدث؛ يقرأ config.LoadFromEnvironmentVariables() متغير البيئة USE_APPLICATION_DEFAULT_CREDENTIALS بدون بادئة).
  • ‫Credentials: (وقت التشغيل فقط، متوافق مع الإصدار v27.0.0 والإصدارات الأحدث) يمكنك إدخال مثيل ICredential أو GoogleCredential تم إنشاؤه مسبقًا مباشرةً في GoogleAdsConfig في وقت التشغيل.

إذا كنت تستخدم OAuth2Mode == APPLICATION، عليك ضبط مفاتيح الإعدادات الإضافية التالية:

  • OAuth2RefreshToken: اضبط هذه القيمة على رمز مميز لإعادة تحميل OAuth 2.0 تم إنشاؤه مسبقًا إذا كنت تريد إعادة استخدام رموز OAuth 2.0 المميزة. هذا الإعداد اختياري.
  • استبدِل OAuth2RedirectUri بعنوان URL لإعادة التوجيه عبر بروتوكول OAuth 2.0. هذا الإعداد اختياري.

راجِع الأدلة التالية لمزيد من التفاصيل:

إذا كنت تستخدم OAuth2Mode == SERVICE_ACCOUNT، عليك ضبط مفاتيح الإعدادات الإضافية التالية:

  • استبدِل OAuth2SecretsJsonPath بمسار ملف مفتاح JSON الخاص ببروتوكول OAuth 2.0.
  • استبدِل OAuth2PrnEmail بعنوان البريد الإلكتروني الخاص بالحساب الذي تنتحل هويته عند استخدام ميزة تفويض الوصول على مستوى النطاق في Google Workspace. هذا الإعداد اختياري.

لمزيد من التفاصيل، يُرجى الاطّلاع على دليل مسار حساب خدمة OAuth.

إعدادات النقل

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

إعدادات Google Ads API

الإعدادات التالية خاصة بواجهة Google Ads API:

  • DeveloperToken: اختياري في v27.3.0 والإصدارات الأحدث (GOOGLE_ADS_DEVELOPER_TOKEN). تم إيقاف الرمز المميز للمطوِّر نهائيًا في 9 سبتمبر 2026. على خادم واجهة برمجة التطبيقات، يتم تحديد مستويات الوصول من خلال مشروعك على Google Cloud بغض النظر عن إصدار مكتبة البرامج، وتتجاهل خوادم واجهة برمجة التطبيقات العنوان developer-token (إلى أن يرفضه رقم الإصدار الرئيسي المستقبلي من Google Ads API). لاستبعاد أو إزالة DeveloperToken من إعداداتك، استخدِم Google.Ads.GoogleAds v27.3.0 أو إصدارًا أحدث، تمت فيه إزالة عملية التأكّد من صحة DeveloperToken من جهة العميل (تتطلّب الإصدارات الأقدم قيمة DeveloperToken غير فارغة لإجراء عملية التأكّد من الصحة محليًا).
  • ‫LoginCustomerId: هذا هو رقم تعريف العميل المصرّح له بالاستخدام في الطلب، بدون شُرط (-).
  • LinkedCustomerId: هذا العنوان مطلوب فقط للطُرق التي تعدّل موارد كيان عندما يتم منح الإذن من خلال &quot;الحسابات المرتبطة&quot; في واجهة مستخدم &quot;إعلانات Google&quot; (المورد AccountLink في Google Ads API). اضبط هذه القيمة على رقم تعريف العميل الخاص بموفّر البيانات الذي يعدّل موارد رقم تعريف العميل المحدّد. يجب ضبطه بدون شرطات (-). مزيد من المعلومات حول الحسابات المرتبطة