التهيئة

توفّر مكتبة عملاء 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 مزدحمة، يمكنك نقل إعدادات المكتبة إلى ملف إعداد خاص بها باستخدام السمة 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);

حقول الإعداد

تسرد الأقسام التالية الإعدادات المتوافقة مع مكتبة ‎ .NET في "إعلانات Google".

إعدادات إمكانية الاتصال

  • 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:

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