توفّر مكتبة عملاء Google Ads 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: إصلاح قواعد الإنشاء في ملف 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);
راجِع القائمة الكاملة لمتغيرات البيئة المتوافقة.
حقول الإعداد
في ما يلي قائمة الإعدادات التي تتيحها مكتبة "إعلانات 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 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). اضبُط هذه القيمة على الرقم التعريفي للعميل الخاص بمقدّم البيانات الذي يعدِّل موارد الرقم التعريفي للعميل المحدّد. ويجب ضبطه بدون واصلات (-
). مزيد من المعلومات حول الحسابات المرتبطة