بنية واجهة برمجة التطبيقات

يقدّم هذا الدليل المكوّنات الأساسية التي تشكّل Google Ads API. تتألف واجهة برمجة التطبيقات Google Ads API من مراجع وخدمات. يمثّل المورد عنصرًا في "إعلانات Google"، بينما تسترد الخدمات عناصر "إعلانات Google" وتعدّلها.

التسلسل الهرمي للعناصر

يمكن عرض حساب على "إعلانات Google" على أنّه تدرّج هرمي للعناصر.

• المورد ذو المستوى الأعلى في الحساب هو العميل.

• يتضمّن كل عميل حملة واحدة أو أكثر من الحملات النشطة.

• تحتوي كل حملة على مجموعة إعلانية واحدة أو أكثر، وتُستخدم لتجميع إعلاناتك في مجموعات منطقية.

• يمثّل إعلان المجموعة الإعلانية إعلانًا تعرضه في مجموعة إعلانية. باستثناء "حملات التطبيقات" التي يمكن أن تتضمّن إعلانًا واحدًا فقط للمجموعة الإعلانية لكل مجموعة إعلانية، تحتوي كل مجموعة إعلانية على إعلان واحد أو أكثر للمجموعة الإعلانية.

تستخدِم حملات الأداء الأفضل بنية مختلفة عن أنواع الحملات الأخرى: فبدلاً من المجموعات الإعلانية والإعلانات ضمن المجموعات الإعلانية، تحتوي "حملة الأداء الأفضل" على مجموعات مواد عرض. يمكنك ربط مواد عرض إبداعية بمجموعة مواد عرض باستخدام AssetGroupAsset وإرفاق إشارات الجمهور أو مواضيع البحث باستخدام AssetGroupSignal.

يمكنك إرفاق مرجع واحد أو أكثر من مراجع AdGroupCriterion أو CampaignCriterion بمجموعة إعلانية أو حملة. تمثّل هذه المعايير الطريقة التي يتم بها عرض الإعلانات.

هناك العديد من أنواع المعايير، مثل الكلمات الرئيسية والفئات العمرية والمواقع الجغرافية. تؤثّر المعايير المحدّدة على مستوى الحملة في جميع الموارد الأخرى ضِمن الحملة. يمكنك أيضًا تحديد الميزانيات وتواريخ وأوقات البدء والانتهاء للحملات أو للإعلانات الفردية باستخدام AdGroupAd.start_date_time وAdGroupAd.end_date_time.

أخيرًا، يمكنك إرفاق مواد العرض على مستوى الحساب أو الحملة أو المجموعة الإعلانية أو مجموعة مواد العرض. تتيح لك مواد العرض تقديم معلومات إضافية إلى إعلاناتك، مثل أرقام الهواتف أو عناوين الشوارع أو العروض الترويجية. نظرة عامة على مواد العرض

الموارد

تمثّل المراجع الكيانات داخل حسابك على "إعلانات Google". Campaign وAdGroup هما مثالان على الموارد.

معرّفات العناصر

يتم تحديد كل عنصر في "إعلانات Google" من خلال رقم تعريف خاص به. بعض أرقام التعريف هذه فريدة على مستوى العالم في جميع حسابات "إعلانات Google"، بينما البعض الآخر فريد فقط ضمن نطاق محدود.

يمكن أن تكون قواعد المعرّفات هذه مفيدة عند تصميم مساحة تخزين محلية لعناصر "إعلانات Google".

يمكن استخدام بعض الكائنات لأنواع متعددة من الكيانات. في مثل هذه الحالات، يحتوي العنصر على حقل type يصف محتواه. على سبيل المثال، يمكن أن يشير AdGroupAd إلى عنصر مثل إعلان متجاوب على شبكة البحث أو إعلان فندق أو إعلان زيادة الطلب. يمكن الوصول إلى هذه القيمة من خلال الحقل AdGroupAd.ad.type، وتعرض القيمة في التعداد AdType. يُرجى العِلم أنّ إمكانية التغيير يمكن أن تختلف حسب الإصدار (على سبيل المثال، VideoResponsiveAdInfo على Ad يمكن تغييره في الإصدار 24 والإصدارات الأحدث).

أسماء الموارد

يتم تحديد كل مورد بشكل فريد من خلال سلسلة resource_name تجمع المورد والعناصر الرئيسية الخاصة به في مسار. على سبيل المثال، تتّخذ أسماء موارد الحملات الشكل التالي:

customers/customer_id/campaigns/campaign_id

بالنسبة إلى حملة تحمل رقم التعريف 987654 في حساب "إعلانات Google" الذي يحمل رقم تعريف العميل 1234567، سيكون resource_name كما يلي:

customers/1234567/campaigns/987654

الخدمات

تتيح لك الخدمات استرداد عناصر "إعلانات Google" وتعديلها. هناك ثلاثة أنواع من الخدمات: خدمات التعديل، وخدمات استرداد الكائنات والإحصاءات، وخدمات استرداد البيانات الوصفية.

تعديل (تغيير) العناصر

تعدّل الخدمات الخاصة بالموارد مثيلات لنوع مورد مرتبط باستخدام طلب mutate. يمكنك أيضًا استخدام GoogleAdsService.Mutate لتنفيذ عمليات تغيير أساسية على مستوى أنواع موارد متعددة في طلب واحد (مثل إنشاء ميزانية حملة وحملة ومجموعة إعلانية معًا).

أمثلة على الخدمات الخاصة بالموارد:

• CustomerService لتعديل العملاء

• CampaignService لتعديل الحملات

• AdGroupService لتعديل المجموعات الإعلانية

يجب أن يتضمّن كل طلب mutate عناصر operation مقابلة. على سبيل المثال، تتوقّع الطريقة CampaignService.MutateCampaigns مثيلاً واحدًا أو أكثر من CampaignOperation. اطّلِع على تغيير الكائنات للحصول على مناقشة مفصّلة حول العمليات.

التعديلات المتزامنة

لا يمكن تعديل عنصر "إعلانات Google" بشكل متزامن من خلال أكثر من مصدر واحد. قد يؤدي ذلك إلى حدوث أخطاء إذا كان لديك عدة مستخدمين يعدّلون الكائن نفسه باستخدام تطبيقك، أو إذا كنت تعدّل كائنات "إعلانات Google" بالتوازي باستخدام سلاسل متعددة. ويشمل ذلك تعديل العنصر من عدّة سلاسل في التطبيق نفسه أو من تطبيقات مختلفة (على سبيل المثال، تطبيقك وجلسة متزامنة لواجهة مستخدم "إعلانات Google").

لا توفّر واجهة برمجة التطبيقات طريقة لقفل عنصر قبل تعديله، فإذا حاول مصدران تعديل عنصر في الوقت نفسه، ستعرض واجهة برمجة التطبيقات الخطأ DatabaseError.CONCURRENT_MODIFICATION_ERROR.

عمليات التغيير المتزامنة وغير المتزامنة

طُرق التعديل في Google Ads API متزامنة. لا تعرض طلبات البيانات من واجهة برمجة التطبيقات ردًا إلا بعد تغيير حالة العناصر، ما يتطلّب انتظار ردّ على كل طلب. على الرغم من أنّ هذا الأسلوب سهل نسبيًا من ناحية الترميز، إلا أنّه قد يؤثّر سلبًا في موازنة التحميل ويؤدي إلى إهدار الموارد إذا تم إجبار العمليات على الانتظار إلى حين اكتمال الطلبات.

هناك طريقة بديلة وهي تعديل العناصر بشكل غير متزامن باستخدام BatchJobService، ما يؤدي إلى تنفيذ مجموعات من العمليات على خدمات متعددة بدون انتظار اكتمالها. بعد إرسال مهمة مجمّعة، تنفّذ خوادم Google Ads API العمليات بشكل غير متزامن، ما يتيح للعمليات تنفيذ عمليات أخرى. يمكنك التحقّق بشكل دوري من حالة المهمة لمعرفة ما إذا اكتملت.

راجِع دليل المعالجة على دفعات لمعرفة المزيد حول المعالجة غير المتزامنة.

التحقّق من صحة التغيير

يمكن التحقّق من صحة معظم طلبات التعديل بدون تنفيذ الطلب فعليًا على البيانات الحقيقية. يمكنك اختبار الطلب بحثًا عن المَعلمات الناقصة وقيم الحقول غير الصحيحة بدون تنفيذ العملية فعليًا.

لاستخدام هذه الميزة، اضبط الحقل الاختياري validate_only المنطقي للطلب على true. يتم التحقّق من صحة الطلب بالكامل كما لو كان سيتم تنفيذه، ولكن يتم تخطّي التنفيذ النهائي. في حال عدم العثور على أي أخطاء، يتم عرض الاستجابة بدون أي نتائج معدَّلة (results فارغ). في حال تعذّر إكمال عملية التحقّق، سيتعذّر إكمال الطلب مع ظهور خطأ GoogleAdsFailure RPC تلقائيًا (partial_failure = false)، أو سيتم عرض استجابة عادية مع أخطاء خاصة بالعملية في partial_failure_error عند partial_failure = true.

validate_only مفيد بشكل خاص في اختبار الإعلانات بحثًا عن المخالفات الشائعة للسياسات. يتم رفض الإعلانات تلقائيًا إذا كانت تنتهك سياسات مثل احتواءها على كلمات أو علامات ترقيم أو أحرف كبيرة أو طول محدّد. يمكن أن يؤدي إعلان مخالِف واحد إلى تعذُّر تحميل دفعة كاملة. يمكن أن يكشف اختبار إعلان جديد ضمن طلب validate_only عن أي انتهاكات من هذا النوع. راجِع مثال الرمز البرمجي الخاص بالتعامل مع أخطاء انتهاك السياسة للاطّلاع على كيفية عمل ذلك.

الحصول على إحصاءات حول العناصر والأداء

‫GoogleAdsService هي الخدمة الموحّدة الوحيدة لاسترداد الكائنات وإحصاءات الأداء.

تتطلّب جميع طلبات Search وSearchStream الخاصة بـ GoogleAdsService طلب بحث يحدّد المورد المطلوب البحث عنه وسمات المورد ومقاييس الأداء المطلوب استردادها والعبارات المنطقية المطلوب استخدامها لفلترة الطلب والشرائح المطلوب استخدامها لتحليل إحصاءات الأداء بشكلٍ أكبر. لمزيد من المعلومات عن شكل طلب البحث، راجِع دليل لغة طلب البحث في "إعلانات Google".

استرداد البيانات الوصفية

تستردّ الدالة GoogleAdsFieldService بيانات وصفية حول الموارد في Google Ads API، مثل السمات المتاحة لأحد الموارد ونوع بياناته. يمكنك الاطّلاع على دليل بيانات وصفية خاصة بالموارد للحصول على تفاصيل حول طلب البحث من هذه الخدمة.

تقدّم هذه الخدمة المعلومات اللازمة لإنشاء طلب بحث إلى GoogleAdsService. لتسهيل الأمر، تتوفّر المعلومات التي تعرضها الدالة GoogleAdsFieldService أيضًا في المستندات المرجعية للحقول.